utopia-project 0.37.6 → 0.38.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/sidebar.js

@@ -11,28 +11,57 @@
 	if (!sidebarNav) return;
 	
 	const navLinks = sidebarNav.querySelectorAll('a[href*="#"]');
-	const sections = Array.from(navLinks).map(link => {
+	
+	// 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 null;
-		const fragment = href.substring(fragmentIndex + 1);
-		// Try to find the section element using the fragment
-		let sectionElement = document.getElementById(fragment);
+		if (fragmentIndex !== -1) {
+			const fragment = href.substring(fragmentIndex + 1);
+			sidebarLinksByFragment.set(fragment, link);
+		}
+	});
+	
+	if (sidebarLinksByFragment.size === 0) return;
+	
+	// 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
+	let lastSeenSidebarId = null;
+	allSections.forEach(({element, id}) => {
+		if (sidebarLinksByFragment.has(id)) {
+			// This section has a sidebar link - use it
+			lastSeenSidebarId = id;
+		}
+		// Annotate the section element with the sidebar link to activate
+		if (lastSeenSidebarId) {
+			element.dataset.sidebarLink = 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 not found, try with CSS.escape for special characters
-		if (!sectionElement && fragment !== CSS.escape(fragment)) {
-			sectionElement = document.querySelector(`#${CSS.escape(fragment)}`);
+		if (!sectionElement && id !== CSS.escape(id)) {
+			sectionElement = document.querySelector(`#${CSS.escape(id)}`);
 		}
 		
-		// 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;
 		}
 		
-		return { link, sectionElement, id: fragment };
-	}).filter(item => item && item.sectionElement);
+		return sectionElement ? { link, sectionElement, id } : null;
+	}).filter(Boolean);
 	
 	if (sections.length === 0) return;
 	
@@ -41,26 +70,30 @@
 	function updateActiveLink(updatePageState = true) {
 		let activeSectionData = null;
 		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
+		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)
+		// Look up which sidebar link should be active using the data attribute
+		if (currentSectionElement && currentSectionElement.dataset.sidebarLink) {
+			const sidebarLinkId = currentSectionElement.dataset.sidebarLink;
+			activeSectionData = sections.find(s => s.id === sidebarLinkId);
+		}
+		
+		// If still no section found, fall back to the last section
 		if (!activeSectionData && sections.length > 0) {
 			activeSectionData = sections[sections.length - 1];
 		}

data/public/_static/site.css

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: utopia-project
 version: !ruby/object:Gem::Version
-  version: 0.37.6
+  version: 0.38.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -174,6 +174,99 @@ files:
 - pages/source/controller.rb
 - pages/source/index.xnode
 - pages/source/show.xnode
+- public/_components/@socketry/syntax/Syntax.js
+- public/_components/@socketry/syntax/Syntax/CodeElement.js
+- public/_components/@socketry/syntax/Syntax/Errors.js
+- public/_components/@socketry/syntax/Syntax/Language.js
+- public/_components/@socketry/syntax/Syntax/Language/apache.js
+- public/_components/@socketry/syntax/Syntax/Language/applescript.js
+- public/_components/@socketry/syntax/Syntax/Language/assembly.js
+- public/_components/@socketry/syntax/Syntax/Language/bash-script.js
+- public/_components/@socketry/syntax/Syntax/Language/bash.js
+- public/_components/@socketry/syntax/Syntax/Language/basic.js
+- public/_components/@socketry/syntax/Syntax/Language/c++.js
+- public/_components/@socketry/syntax/Syntax/Language/c.js
+- public/_components/@socketry/syntax/Syntax/Language/clang.js
+- public/_components/@socketry/syntax/Syntax/Language/cpp.js
+- public/_components/@socketry/syntax/Syntax/Language/csharp.js
+- public/_components/@socketry/syntax/Syntax/Language/css.js
+- public/_components/@socketry/syntax/Syntax/Language/diff.js
+- public/_components/@socketry/syntax/Syntax/Language/go.js
+- public/_components/@socketry/syntax/Syntax/Language/haskell.js
+- public/_components/@socketry/syntax/Syntax/Language/html.js
+- public/_components/@socketry/syntax/Syntax/Language/io.js
+- public/_components/@socketry/syntax/Syntax/Language/java.js
+- public/_components/@socketry/syntax/Syntax/Language/javascript.js
+- public/_components/@socketry/syntax/Syntax/Language/json.js
+- public/_components/@socketry/syntax/Syntax/Language/lisp.js
+- public/_components/@socketry/syntax/Syntax/Language/lua.js
+- public/_components/@socketry/syntax/Syntax/Language/markdown.js
+- public/_components/@socketry/syntax/Syntax/Language/nginx.js
+- public/_components/@socketry/syntax/Syntax/Language/objective-c.js
+- public/_components/@socketry/syntax/Syntax/Language/ocaml.js
+- public/_components/@socketry/syntax/Syntax/Language/pascal.js
+- public/_components/@socketry/syntax/Syntax/Language/patch.js
+- public/_components/@socketry/syntax/Syntax/Language/perl5.js
+- public/_components/@socketry/syntax/Syntax/Language/php-script.js
+- public/_components/@socketry/syntax/Syntax/Language/php.js
+- public/_components/@socketry/syntax/Syntax/Language/plain.js
+- public/_components/@socketry/syntax/Syntax/Language/protobuf.js
+- public/_components/@socketry/syntax/Syntax/Language/python.js
+- public/_components/@socketry/syntax/Syntax/Language/ruby.js
+- public/_components/@socketry/syntax/Syntax/Language/scala.js
+- public/_components/@socketry/syntax/Syntax/Language/smalltalk.js
+- public/_components/@socketry/syntax/Syntax/Language/sql.js
+- public/_components/@socketry/syntax/Syntax/Language/super-collider.js
+- public/_components/@socketry/syntax/Syntax/Language/swift.js
+- public/_components/@socketry/syntax/Syntax/Language/xml.js
+- public/_components/@socketry/syntax/Syntax/Language/xrb.js
+- public/_components/@socketry/syntax/Syntax/Language/yaml.js
+- public/_components/@socketry/syntax/Syntax/Loader.js
+- public/_components/@socketry/syntax/Syntax/Match.js
+- public/_components/@socketry/syntax/Syntax/Rule.js
+- public/_components/@socketry/syntax/license.md
+- public/_components/@socketry/syntax/package.json
+- public/_components/@socketry/syntax/readme.md
+- public/_components/@socketry/syntax/themes/base/apache.css
+- public/_components/@socketry/syntax/themes/base/applescript.css
+- public/_components/@socketry/syntax/themes/base/assembly.css
+- public/_components/@socketry/syntax/themes/base/bash.css
+- public/_components/@socketry/syntax/themes/base/basic.css
+- public/_components/@socketry/syntax/themes/base/c.css
+- public/_components/@socketry/syntax/themes/base/clang.css
+- public/_components/@socketry/syntax/themes/base/csharp.css
+- public/_components/@socketry/syntax/themes/base/css.css
+- public/_components/@socketry/syntax/themes/base/diff.css
+- public/_components/@socketry/syntax/themes/base/go.css
+- public/_components/@socketry/syntax/themes/base/haskell.css
+- public/_components/@socketry/syntax/themes/base/html.css
+- public/_components/@socketry/syntax/themes/base/io.css
+- public/_components/@socketry/syntax/themes/base/java.css
+- public/_components/@socketry/syntax/themes/base/javascript.css
+- public/_components/@socketry/syntax/themes/base/json.css
+- public/_components/@socketry/syntax/themes/base/lisp.css
+- public/_components/@socketry/syntax/themes/base/lua.css
+- public/_components/@socketry/syntax/themes/base/markdown.css
+- public/_components/@socketry/syntax/themes/base/nginx.css
+- public/_components/@socketry/syntax/themes/base/ocaml.css
+- public/_components/@socketry/syntax/themes/base/pascal.css
+- public/_components/@socketry/syntax/themes/base/perl5.css
+- public/_components/@socketry/syntax/themes/base/php-script.css
+- public/_components/@socketry/syntax/themes/base/php.css
+- public/_components/@socketry/syntax/themes/base/plain.css
+- public/_components/@socketry/syntax/themes/base/protobuf.css
+- public/_components/@socketry/syntax/themes/base/python.css
+- public/_components/@socketry/syntax/themes/base/ruby.css
+- public/_components/@socketry/syntax/themes/base/scala.css
+- public/_components/@socketry/syntax/themes/base/smalltalk.css
+- public/_components/@socketry/syntax/themes/base/sql.css
+- public/_components/@socketry/syntax/themes/base/super-collider.css
+- public/_components/@socketry/syntax/themes/base/swift.css
+- public/_components/@socketry/syntax/themes/base/syntax.css
+- public/_components/@socketry/syntax/themes/base/xml.css
+- public/_components/@socketry/syntax/themes/base/xrb.css
+- public/_components/@socketry/syntax/themes/base/yaml.css
+- public/_components/@socketry/syntax/themes/theming.md
 - public/_components/jquery-litebox/jquery.litebox.css
 - public/_components/jquery-litebox/jquery.litebox.gallery.css
 - public/_components/jquery-litebox/jquery.litebox.js