utopia-project 0.37.6 → 0.39.0

data/public/_components/@socketry/syntax/themes/theming.md

@@ -0,0 +1,233 @@
+# Theming Guide
+
+The `@socketry/syntax` library uses CSS custom properties (variables) with HSL colors to provide a flexible and maintainable theming system.
+
+## Key Benefits
+
+1. **Ultra Simple**: Change just 3 variables to create a complete theme
+2. **Automatic Dark Mode**: Light and dark mode handled automatically
+3. **Automatic Color Harmony**: All colors derived from one base color using hue rotation
+4. **Easy Customization**: Override the base or individual colors as needed
+
+## Theme Architecture
+
+### The Base Color System
+
+Everything derives from three base variables:
+
+```css
+:host {
+	--syntax-base-hue: 270;           /* 0-360 degrees on the color wheel */
+	--syntax-base-saturation: 60%;    /* How vibrant the colors are */
+	--syntax-base-lightness: 50%;     /* How light/dark the colors are */
+}
+```
+
+**Dark mode** just adjusts saturation and lightness:
+
+```css
+@media (prefers-color-scheme: dark) {
+	:host {
+		--syntax-base-saturation: 50%;  /* Slightly less saturated */
+		--syntax-base-lightness: 70%;   /* Much lighter for dark backgrounds */
+	}
+}
+```
+
+### Automatic Color Derivation
+
+All token colors are automatically calculated using hue rotation:
+
+```css
+--syntax-keyword: hsl(calc(var(--syntax-base-hue) + 30), ...);   /* 30° rotation */
+--syntax-string: hsl(calc(var(--syntax-base-hue) - 90), ...);    /* 90° opposite */
+--syntax-function: hsl(calc(var(--syntax-base-hue) - 60), ...);  /* 60° rotation */
+/* etc. */
+```
+
+This ensures all colors are harmonious and work together!
+
+## Creating Custom Themes
+
+### Method 1: Change the Base Hue (Recommended)
+
+The simplest approach - just pick a different base color:
+
+```css
+.ocean-theme {
+	--syntax-base-hue: 200;  /* Blue - everything becomes ocean-themed! */
+}
+
+.sunset-theme {
+	--syntax-base-hue: 30;   /* Orange - warm sunset colors */
+}
+
+.forest-theme {
+	--syntax-base-hue: 140;  /* Green - natural forest palette */
+}
+```
+
+Then apply it:
+
+```html
+<syntax-code language="javascript" class="ocean-theme">
+	// Your code here
+</syntax-code>
+```
+
+### Method 2: Adjust Saturation and Lightness
+
+For more subtle themes:
+
+```css
+.pastel-theme {
+	--syntax-base-saturation: 40%;  /* Less vibrant */
+	--syntax-base-lightness: 65%;   /* Lighter */
+}
+
+.vivid-theme {
+	--syntax-base-saturation: 90%;  /* Very saturated */
+	--syntax-base-lightness: 45%;   /* Slightly darker */
+}
+```
+
+### Method 3: Override Specific Colors
+
+For fine-grained control:
+
+```css
+.custom-theme {
+	--syntax-base-hue: 280;  /* Purple base */
+	
+	/* But make strings green instead of the derived color */
+	--syntax-string: hsl(120, 60%, 40%);
+}
+```
+
+### Method 4: Custom Dark Mode
+
+Override dark mode values for specific themes:
+
+```css
+.my-theme {
+	--syntax-base-hue: 200;
+}
+
+@media (prefers-color-scheme: dark) {
+	.my-theme {
+		/* Different hue in dark mode */
+		--syntax-base-hue: 180;
+		--syntax-base-saturation: 45%;
+		--syntax-base-lightness: 75%;
+	}
+}
+```
+
+## Token Types
+
+All token types automatically get colors derived from the base. You can override individual ones if needed:
+
+### Programming Language Tokens
+
+- `keyword` - Language keywords (if, function, class)
+- `string` - String literals
+- `comment` - Code comments
+- `number` - Numeric literals
+- `operator` - Operators (+, -, *, etc.)
+- `function` - Function names
+- `constant` - Constants and literals
+- `type` - Type names
+- `preprocessor` - Preprocessor directives
+- `access` - Access modifiers (public, private)
+- `escape` - Escape sequences
+
+### HTML/XML Tokens
+
+- `tag` - HTML/XML tags
+- `tag-name` - Tag names
+- `attribute` - Attributes
+- `entity` - HTML entities
+- `doctype` - DOCTYPE declarations
+- `cdata` - CDATA sections
+
+### Semantic Markdown Tokens
+
+- `heading` - Headers (# Heading)
+- `strong` - Bold text (**bold**)
+- `emphasis` - Italic text (*italic*)
+- `code` - Code blocks and inline code
+- `link` - Links and images
+- `quote` - Blockquotes
+- `list-marker` - List markers
+
+## Dark Mode
+
+Dark mode colors are automatically applied using `prefers-color-scheme`:
+
+```css
+@media (prefers-color-scheme: dark) {
+	:host {
+		--syntax-keyword: hsl(var(--syntax-hue-primary), 50%, 70%);
+		/* Automatically lighter and less saturated for dark backgrounds */
+	}
+}
+```
+
+You can override dark mode colors in your custom theme:
+
+```css
+.my-theme {
+	--syntax-keyword: hsl(300, 80%, 40%);
+}
+
+@media (prefers-color-scheme: dark) {
+	.my-theme {
+		--syntax-keyword: hsl(300, 60%, 75%);
+	}
+}
+```
+
+## Example Themes
+
+### Monochrome
+
+```css
+.monochrome {
+	--syntax-keyword: hsl(0, 0%, 20%);
+	--syntax-string: hsl(0, 0%, 30%);
+	--syntax-comment: hsl(0, 0%, 60%);
+	--syntax-function: hsl(0, 0%, 25%);
+}
+```
+
+### High Contrast
+
+```css
+.high-contrast {
+	--syntax-hue-primary: 270;
+	/* Increase saturation and contrast */
+	--syntax-keyword: hsl(var(--syntax-hue-primary), 100%, 30%);
+	--syntax-string: hsl(0, 100%, 35%);
+	--syntax-comment: hsl(0, 0%, 40%);
+}
+```
+
+### Pastel
+
+```css
+.pastel {
+	/* Use same hues but with high lightness and low saturation */
+	--syntax-keyword: hsl(var(--syntax-hue-primary), 40%, 60%);
+	--syntax-string: hsl(var(--syntax-hue-tertiary), 40%, 60%);
+	--syntax-comment: hsl(var(--syntax-hue-neutral), 20%, 70%);
+}
+```
+
+## Tips
+
+1. **Hue Relationships**: Use complementary (180° apart) or analogous (30° apart) hues for harmony
+2. **Saturation**: Lower saturation (20-40%) for subtle themes, higher (70-90%) for vibrant themes
+3. **Lightness**: Keep 30-50% for light mode, 60-80% for dark mode
+4. **Contrast**: Ensure sufficient contrast between text and background (WCAG AA: 4.5:1 minimum)
+5. **Testing**: Test themes in both light and dark mode
+6. **Consistency**: Use the hue variables to maintain color relationships across tokens

data/public/_static/application.js

@@ -0,0 +1,24 @@
+/**
+ * Application Initialization
+ * Main entry point for client-side functionality
+ */
+
+// Import dependencies:
+import {Syntax} from '@socketry/syntax';
+import mermaid from 'mermaid';
+import {initializeSectionHeadingLinks} from './links.js';
+import {SidebarNavigation} from './sidebar.js';
+
+// Initialize Mermaid with theme detection:
+const isDarkMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
+const theme = isDarkMode ? 'dark' : 'default';
+mermaid.initialize({startOnLoad: true, theme: theme});
+
+// Initialize section self-links:
+initializeSectionHeadingLinks();
+
+// Initialize sidebar navigation:
+SidebarNavigation.initialize();
+
+// Initialize syntax highlighting:
+await Syntax.highlight();

data/public/_static/links.js

@@ -1,21 +1,23 @@
-jQuery(function() {
-	$.each($('section[id]'), function(index, element) {
-		let anchor = document.createElement('a');
-		
-		anchor.appendChild(
-			document.createTextNode("¶")
-		);
+/**
+ * Section Heading Links
+ * Adds pilcrow (¶) self-links to section headings for easy linking
+ */
+
+export function initializeSectionHeadingLinks() {
+	const sections = document.querySelectorAll('section[id]');
+	
+	sections.forEach(element => {
+		const anchor = document.createElement('a');
 		
+		anchor.appendChild(document.createTextNode("¶"));
 		anchor.href = "#" + element.id;
 		anchor.className = "self";
 		
-		let heading = element.firstChild;
-		anchor.title = heading.innerText;
-		
-		heading.appendChild(
-			document.createTextNode(' ')
-		);
-		
-		heading.appendChild(anchor);
+		const heading = element.firstChild;
+		if (heading) {
+			anchor.title = heading.innerText;
+			heading.appendChild(document.createTextNode(' '));
+			heading.appendChild(anchor);
+		}
 	});
-});
+}

data/public/_static/sidebar.js

@@ -3,105 +3,191 @@
  * Progressive enhancement for sidebar navigation with scroll tracking
  */
 
-(function() {
-	'use strict';
+class SidebarNavigation {
+	static extractFragment(href) {
+		const index = href.indexOf('#');
+		return index !== -1 ? href.substring(index + 1) : null;
+	}
 	
-	// Only run if we have a sidebar navigation
-	const sidebarNav = document.querySelector('.sidebar nav');
-	if (!sidebarNav) return;
+	constructor(sidebarNav, sidebarLinksByFragment, allSections, sections, navLinks, sectionToSidebarLinkMap) {
+		this.sidebarNav = sidebarNav;
+		this.navLinks = navLinks;
+		this.currentActive = null;
+		this.sidebarLinksByFragment = sidebarLinksByFragment;
+		this.allSections = allSections;
+		this.sections = sections;
+		this.sectionToSidebarLinkMap = sectionToSidebarLinkMap;
+		
+		// Store references for cleanup
+		this.scrollTimer = null;
+		this.scrollHandler = null;
+		this.resizeHandler = null;
+		this.clickHandlers = new Map();
+		
+		// Initialize
+		this.setupEventListeners();
+		
+		// Initial update without changing page state (preserves URL fragments)
+		this.updateActiveLink(false);
+	}
+	
+	setupEventListeners() {
+		// Throttled scroll handler
+		this.scrollHandler = () => {
+			if (this.scrollTimer) return;
+			
+			this.scrollTimer = setTimeout(() => {
+				this.updateActiveLink();
+				this.scrollTimer = null;
+			}, 100);
+		};
+		
+		this.resizeHandler = () => this.updateActiveLink();
+		
+		// Set up event listeners
+		window.addEventListener('scroll', this.scrollHandler, { passive: true });
+		window.addEventListener('resize', this.resizeHandler, { passive: true });
+		
+		// Smooth scroll enhancement for sidebar navigation links
+		this.navLinks.forEach(link => {
+			const clickHandler = (event) => {
+				const href = link.getAttribute('href');
+				const fragment = SidebarNavigation.extractFragment(href);
+				
+				if (!fragment) return;
+				
+				const target = document.getElementById(fragment);
+				
+				if (target) {
+					event.preventDefault();
+					
+					// Update URL to trigger :target and let browser handle scrolling
+					window.location.hash = fragment;
+					
+					link.focus();
+				}
+			};
+			
+			this.clickHandlers.set(link, clickHandler);
+			link.addEventListener('click', clickHandler);
+		});
+	}
 	
-	const navLinks = sidebarNav.querySelectorAll('a[href*="#"]');
-	const sections = Array.from(navLinks).map(link => {
-		const href = link.getAttribute('href');
-		// Extract fragment from both "#section" and "page.html#section" formats
-		const fragmentIndex = href.indexOf('#');
-		if (fragmentIndex === -1) return null;
-		const fragment = href.substring(fragmentIndex + 1);
-		// Try to find the section element using the fragment
-		let sectionElement = document.getElementById(fragment);
-		
-		// If not found, try with CSS.escape for special characters
-		if (!sectionElement && fragment !== CSS.escape(fragment)) {
-			sectionElement = document.querySelector(`#${CSS.escape(fragment)}`);
+	destroy() {
+		// Clear any pending timer
+		if (this.scrollTimer) {
+			clearTimeout(this.scrollTimer);
+			this.scrollTimer = null;
 		}
 		
-		// The element we found should be the section container, not just the heading
-		// If it's a heading, find its parent section
-		if (sectionElement && sectionElement.tagName.match(/^H[1-6]$/)) {
-			sectionElement = sectionElement.closest('section') || sectionElement.parentElement;
+		// Remove window event listeners
+		if (this.scrollHandler) {
+			window.removeEventListener('scroll', this.scrollHandler);
+			this.scrollHandler = null;
 		}
 		
-		return { link, sectionElement, id: fragment };
-	}).filter(item => item && item.sectionElement);
-	
-	if (sections.length === 0) return;
-	
-	let currentActive = null;
+		if (this.resizeHandler) {
+			window.removeEventListener('resize', this.resizeHandler);
+			this.resizeHandler = null;
+		}
+		
+		// Remove click handlers from all links
+		this.clickHandlers.forEach((handler, link) => {
+			link.removeEventListener('click', handler);
+		});
+		this.clickHandlers.clear();
+		
+		// Clear the section-to-sidebar-link mapping
+		this.sectionToSidebarLinkMap.clear();
+		
+		// Remove active class from current link
+		if (this.currentActive) {
+			this.currentActive.link.classList.remove('active');
+			this.currentActive = null;
+		}
+	}
 	
-	function updateActiveLink(updatePageState = true) {
-		let activeSectionData = null;
+	findCurrentSection() {
 		let smallestValidBottom = Infinity;
+		let currentSectionElement = null;
 		
-		// Find the section with the smallest bottom position that is still >= 0
-		// This gives us the section that we're currently reading through
-		sections.forEach((sectionData) => {
-			const { sectionElement } = sectionData;
-			const rect = sectionElement.getBoundingClientRect();
+		// Find which section the user is currently viewing
+		this.allSections.forEach(({element}) => {
+			const rect = element.getBoundingClientRect();
 			const sectionBottom = rect.bottom;
 			
 			// Get the actual bottom padding for this section
-			const bottomPadding = parseFloat(getComputedStyle(sectionElement).paddingBottom);
+			const bottomPadding = parseFloat(getComputedStyle(element).paddingBottom);
 			
 			// We want the section whose bottom is closest to the top but still visible
 			if (sectionBottom > bottomPadding && sectionBottom < smallestValidBottom) {
 				smallestValidBottom = sectionBottom;
-				activeSectionData = sectionData;
+				currentSectionElement = element;
 			}
 		});
 		
-		// If no section has bottom >= 0, fall back to the last section
-		// (meaning we've scrolled past all content)
-		if (!activeSectionData && sections.length > 0) {
-			activeSectionData = sections[sections.length - 1];
+		// Look up which sidebar link should be active using the map
+		if (currentSectionElement) {
+			const sidebarLinkId = this.sectionToSidebarLinkMap.get(currentSectionElement);
+			if (sidebarLinkId) {
+				return this.sections.find(s => s.id === sidebarLinkId);
+			}
+		}
+		
+		// If no section found, fall back to the last section
+		return this.sections.length > 0 ? this.sections[this.sections.length - 1] : null;
+	}
+	
+	setActiveSection(activeSectionData) {
+		// Remove previous active
+		if (this.currentActive) {
+			this.currentActive.link.classList.remove('active');
 		}
 		
-		// Update active link
-		if (activeSectionData !== currentActive) {
-			// Remove previous active
-			if (currentActive) {
-				currentActive.link.classList.remove('active');
+		// Set new active
+		if (activeSectionData) {
+			activeSectionData.link.classList.add('active');
+			this.currentActive = activeSectionData;
+		} else {
+			this.currentActive = null;
+		}
+	}
+	
+	updateUrlFragment(sectionId) {
+		if (sectionId) {
+			const newFragment = '#' + sectionId;
+			if (window.location.hash !== newFragment) {
+				history.replaceState(null, null, newFragment);
+			}
+		} else {
+			// Clear fragment if no active section
+			if (window.location.hash) {
+				history.replaceState(null, null, window.location.pathname);
 			}
+		}
+	}
+	
+	updateActiveLink(updatePageState = true) {
+		const activeSectionData = this.findCurrentSection();
+		
+		// Only update if section changed
+		if (activeSectionData !== this.currentActive) {
+			this.setActiveSection(activeSectionData);
 			
-			// Set new active
-			if (activeSectionData) {
-				activeSectionData.link.classList.add('active');
-				currentActive = activeSectionData;
-				
-				if (updatePageState) {
-					// Update URL fragment to reflect current section
-					const newFragment = '#' + activeSectionData.id;
-					if (window.location.hash !== newFragment) {
-						history.replaceState(null, null, newFragment);
-					}
-					
-					// Auto-scroll sidebar to keep active item visible
-					scrollToActiveItem(activeSectionData.link);
-				}
-			} else {
-				currentActive = null;
-				
-				if (updatePageState) {
-					// Clear fragment if no active section
-					if (window.location.hash) {
-						history.replaceState(null, null, window.location.pathname);
-					}
+			if (updatePageState) {
+				if (activeSectionData) {
+					this.updateUrlFragment(activeSectionData.id);
+					this.scrollToActiveItem(activeSectionData.link);
+				} else {
+					this.updateUrlFragment(null);
 				}
 			}
 		}
 	}
 	
-	function scrollToActiveItem(activeLink) {
-		const sidebar = activeLink.closest('.sidebar');
+	scrollToActiveItem(activeLink) {
+		// Use the sidebar nav container we already have
+		const sidebar = this.sidebarNav.closest('.sidebar');
 		if (!sidebar) return;
 		
 		const sidebarRect = sidebar.getBoundingClientRect();
@@ -126,50 +212,69 @@
 		}
 	}
 	
-	// Throttled scroll handler
-	let scrollTimer = null;
-	
-	function onScroll() {
-		if (scrollTimer) return;
+	// Static method to initialize with default selector
+	static initialize(selector = '.sidebar nav') {
+		const sidebarNav = document.querySelector(selector);
+		if (!sidebarNav) return null;
 		
-		scrollTimer = setTimeout(() => {
-			updateActiveLink();
-			scrollTimer = null;
-		}, 100);
-	}
-	
-	// Initialize and set up event listeners
-	window.addEventListener('scroll', onScroll, { passive: true });
-	window.addEventListener('resize', updateActiveLink, { passive: true });
-	
-	// Initial update without changing page state (preserves URL fragments):
-	updateActiveLink(false);
-	
-	// Smooth scroll enhancement for sidebar navigation links
-	navLinks.forEach(link => {
-		link.addEventListener('click', (event) => {
+		const navLinks = sidebarNav.querySelectorAll('a[href*="#"]');
+		
+		// Build a map of sidebar links by their fragment IDs
+		const sidebarLinksByFragment = new Map();
+		navLinks.forEach(link => {
 			const href = link.getAttribute('href');
-			// Extract fragment from both "#section" and "page.html#section" formats
-			const fragmentIndex = href.indexOf('#');
-			if (fragmentIndex === -1) return;
-			const fragment = href.substring(fragmentIndex + 1);
+			const fragment = SidebarNavigation.extractFragment(href);
 			
-			// Try to find the target using the fragment
-			let target = document.getElementById(fragment);
-			
-			// If not found, try with CSS.escape for special characters
-			if (!target && fragment !== CSS.escape(fragment)) {
-				target = document.querySelector(`#${CSS.escape(fragment)}`);
+			if (fragment) {
+				sidebarLinksByFragment.set(fragment, link);
+			}
+		});
+		
+		// Early exit if no sidebar links with fragments
+		if (sidebarLinksByFragment.size === 0) return null;
+		
+		// Get all sections/headings on the page and annotate them with their sidebar link
+		const allSections = Array.from(document.querySelectorAll('section, h1, h2, h3, h4, h5, h6'))
+			.filter(el => el.id) // Only keep elements with IDs
+			.map(el => {
+				// Get the section element (section or heading's parent)
+				const sectionElement = el.tagName === 'SECTION' ? el : (el.closest('section') || el.parentElement);
+				return { element: sectionElement, id: el.id };
+			});
+		
+		// Annotate each section with which sidebar link should be active
+		// Walk through in DOM order and track the "last seen" sidebar link
+		// Store mapping in a Map instead of mutating DOM with data attributes
+		const sectionToSidebarLinkMap = new Map();
+		let lastSeenSidebarId = null;
+		allSections.forEach(({element, id}) => {
+			if (sidebarLinksByFragment.has(id)) {
+				// This section has a sidebar link - use it
+				lastSeenSidebarId = id;
+			}
+			// Map the section element to the sidebar link to activate
+			if (lastSeenSidebarId) {
+				sectionToSidebarLinkMap.set(element, lastSeenSidebarId);
 			}
+		});
+		
+		// Build sections array with link references for active state tracking
+		const sections = Array.from(sidebarLinksByFragment.entries()).map(([id, link]) => {
+			let sectionElement = document.getElementById(id);
 			
-			if (target) {
-				event.preventDefault();
-				
-				// Update URL to trigger :target and let browser handle scrolling
-				window.location.hash = fragment;
+			if (sectionElement && sectionElement.tagName.match(/^H[1-6]$/)) {
+				sectionElement = sectionElement.closest('section') || sectionElement.parentElement;
 			}
+			
+			return sectionElement ? { link, sectionElement, id } : null;
+		}).filter(Boolean);
+		
+		// Early exit if no valid sections found
+		if (sections.length === 0) return null;
+		
+		// All checks passed - create the instance
+		return new SidebarNavigation(sidebarNav, sidebarLinksByFragment, allSections, sections, navLinks, sectionToSidebarLinkMap);
+	}
+}
 
-			link.focus();
-		});
-	});
-})();
+export { SidebarNavigation };

data/public/_static/site.css

@@ -244,10 +244,6 @@ div.giscus {
 	padding: 0 1rem;
 }
 
-pre {
-	margin: 2rem 1rem;
-}
-
 h1 span {
 	display: inline-block;
 }