utopia-project 0.38.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ba83cfcaea0e83dbd4e927e4ed1483fa7079c94b56c9a480616a421b04fcaa
-  data.tar.gz: 48b8ceb3698e82e2d3f460f53f5e085540251c4e054abe0ff0560133de2d5d40
+  metadata.gz: 9857e236b8690b3e3c8ae113309fdf2af695222643cc998bcac8862c09232465
+  data.tar.gz: b8ccb22331616e6f1ff287c067bf22ace7148c7627a6be9209be9c86f928a87d
 SHA512:
-  metadata.gz: e59af3ae609bd5d28aafaaf9af6d7d50acb365e625986b8983277fe71d0615afb95552f32b24d27c586c15417c4e1e376db1353968d116b8dedf7c919b0e8286
-  data.tar.gz: 6e3652aa2c16b3406afb0c8ab4cb47d2f259ad5b2c15e4c368c50d6df6214e60c79e3c11ca4d592f54e4b5332dd30fe3d8f3876f9ff4fee34ecc961a9548f7b5
+  metadata.gz: c9e2c1640bb841704474c7bf6e3bf1a077fa9eae05267fb45874ea5b07c2beefcdfd92011d152e55db42fff3a1b037611355ddcd94e9f43b6425049f765e4741
+  data.tar.gz: 21796bcb1f5844dce244d0421a92d86ee3e25a0bf8daa05e12e6c41103fbc0e64f6703f8de664e1ce1110509876f0073850e55980c95847a8c492959ec14da3c

data/lib/utopia/project/base.rb

@@ -15,7 +15,7 @@ require "thread/local"
 require_relative "document"
 require_relative "releases_document"
 
-require_relative "guide"
+require_relative "guides"
 require_relative "linkify"
 
 module Utopia
@@ -193,10 +193,8 @@ module Utopia
 				end
 			end
 			
-			# Enumerate over all available guides in order.
-			# @yields {|guide| ...} If a block is given.
-			# 	@parameter guide [Guide]
-			# @returns [Enumerator(Guide)] If no block given.
+			# Get the guides collection for this project.
+			# @returns [Guides]
 			#
 			# @example List guide titles
 			# 	base = Utopia::Project::Base.new
@@ -204,15 +202,7 @@ module Utopia
 			# 		puts guide.title
 			# 	end
 			def guides
-				return to_enum(:guides) unless block_given?
-				
-				@links.index("/guides").each do |link|
-					guide_path = File.join(@root, link.path)
-					
-					next unless File.directory?(guide_path)
-					
-					yield Guide.new(self, guide_path, link.info)
-				end
+				@guides ||= Guides.new(self, @links)
 			end
 			
 			def readme_document

data/lib/utopia/project/guides.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "guide"
+
+module Utopia
+	module Project
+		# A collection of guides with navigation and lookup capabilities.
+		class Guides
+			include Enumerable
+			
+			# Initialize the guides collection.
+			# @parameter base [Base] The base instance for the project.
+			# @parameter links [Object] The links index for finding guides.
+			def initialize(base, links)
+				@base = base
+				@links = links
+			end
+			
+			# Iterate over all guides.
+			# @yields {|guide| ...} If a block is given.
+			# 	@parameter guide [Guide]
+			# @returns [Enumerator(Guide)] If no block is given.
+			def each(&block)
+				return to_enum(:each) unless block_given?
+				
+				@links.index("/guides").each do |link|
+					guide_path = File.join(@base.root, link.path)
+					
+					next unless File.directory?(guide_path)
+					
+					yield Guide.new(@base, guide_path, link.info)
+				end
+			end
+			
+			# Get all guides as a sorted array.
+			# @returns [Array(Guide)]
+			def to_a
+				@array ||= super.sort
+			end
+			
+			# Find a guide by name.
+			# @parameter name [String] The guide name.
+			# @returns [Guide | Nil]
+			def [](name)
+				to_a.find { |guide| guide.name == name }
+			end
+			
+			# Get the related guides (previous and next) for the given guide.
+			# @parameter guide [Guide] The current guide.
+			# @returns [Array(Guide | Nil, Guide | Nil)] A two-element array containing the previous and next guides.
+			def related(guide)
+				index = to_a.index { |g| g.name == guide.name }
+				return [nil, nil] unless index
+				
+				previous_guide = index > 0 ? to_a[index - 1] : nil
+				next_guide = index < to_a.size - 1 ? to_a[index + 1] : nil
+				
+				[previous_guide, next_guide]
+			end
+		end
+	end
+end
+

data/lib/utopia/project/import_map.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "utopia/import_map"
 
 module Utopia

data/lib/utopia/project/sidebar.rb

@@ -90,24 +90,14 @@ module Utopia
 			private
 			
 			def self.extract_headings_from_document(document)
-				headings = []
-				return headings unless document&.root
+				return [] unless document&.root
 				
-				document.root.walk do |node|
-					if node.type == :header
-						next if node.header_level < 2 or node.header_level > 3
-						
-						fragment = node.dup.extract_children
-						
-						title = XRB::Markup.raw(fragment.to_html)
-						level = node.header_level
-						anchor = Markly::Renderer::HTML.anchor_for(fragment)
-						
-						headings << Entry.new(title, level, anchor)
-					end
+				Markly::Renderer::Headings.extract(document.root, min_level: 2, max_level: 3).map do |heading|
+					fragment = heading.node.dup.extract_children
+					title = XRB::Markup.raw(fragment.to_html)
+					
+					Entry.new(title, heading.level, heading.anchor)
 				end
-				
-				headings
 			end
 		end
 	end

data/lib/utopia/project/version.rb

@@ -5,6 +5,6 @@
 
 module Utopia
 	module Project
-		VERSION = "0.38.0"
+		VERSION = "0.40.0"
 	end
 end

data/pages/_page.xnode

@@ -16,24 +16,7 @@
 		<link rel="stylesheet" href="/_static/site.css" type="text/css" media="screen" />
 		
 		#{Utopia::Project::IMPORT_MAP.relative_to(request.env["REQUEST_PATH"]).to_html}
-		
-		<script src="/_components/jquery/jquery.min.js"></script>
-		
-		<script src="/_static/links.js"></script>
-
-		<script type="module">
-		// <![CDATA[
-			import {Syntax} from '@socketry/syntax';
-			document.addEventListener('DOMContentLoaded', async function() {
-				await Syntax.highlight();
-			});
-			
-			import mermaid from 'mermaid';
-			const isDarkMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
-			const theme = isDarkMode ? 'dark' : 'default';
-			mermaid.initialize({startOnLoad: true, theme: theme});
-		// ]]>
-		</script>
+		<script type="module" src="/_static/application.js"></script>
 	</head>
 	<body>
 		<content:header />

data/pages/_usage.xnode

@@ -3,7 +3,7 @@
 <?r
 	base = self[:base]
 	
-	base.guides do |guide|
+	base.guides.each do |guide|
 ?>
 	<section>
 		<h3><a href="#{guide.href}">#{guide.title}</a></h3>
@@ -18,4 +18,4 @@
 	</section>
 <?r
 	end
-?>
+?>

data/pages/guides/index.xnode

@@ -1,16 +1,25 @@
 <content:page>
-	<?r
-		base = self[:base]
-	?>
 	<content:heading>Guides</content:heading>
 	
-	<ul>
+	<section>
 		<?r
-		base = controller[:base]
+		base = self[:base]
 		
-		base.guides do |guide|
-			?><li><a href="#{guide.name}/">#{guide.title}</a></li><?r
+		base.guides.each do |guide|
+		?>
+		<section>
+			<h3><a href="#{guide.href}">#{guide.title}</a></h3>
+			
+			<?r if description = guide.description ?>
+				#{Markup.raw description.to_html}
+			<?r elsif documentation = guide.documentation ?>
+				#{base.format(documentation.text, language: guide.documentation.language)}
+			<?r else ?>
+				<p>No description.</p>
+			<?r end ?>
+		</section>
+		<?r
 		end
 		?>
-	</ul>
+	</section>
 </content:page>

data/pages/guides/show.xnode

@@ -9,6 +9,24 @@
 		#{navigation.to_html}
 	</aside>
 	<div class="content">
+		<?r
+			previous_guide, next_guide = base.guides.related(guide)
+			
+			if previous_guide or next_guide
+				?>
+				<nav class="top">
+					<?r if previous_guide
+						?><a href="#{previous_guide.href}" class="previous">← #{previous_guide.title}</a><?r
+					end
+					
+					if next_guide
+						?><a href="#{next_guide.href}" class="next">#{next_guide.title} →</a><?r
+					end ?>
+				</nav>
+				<?r
+			end
+		?>
+		
 		<content:heading>#{guide.title}</content:heading>
 		
 		<?r
@@ -27,6 +45,21 @@
 				end
 			end
 		?>
+		
+		<?r
+			if previous_guide or next_guide
+				?>
+				<nav class="bottom">
+					<?r if previous_guide
+						?><a href="#{previous_guide.href}" class="previous">← #{previous_guide.title}</a><?r
+					end
+					
+					if next_guide
+						?><a href="#{next_guide.href}" class="next">#{next_guide.title} →</a><?r
+					end ?>
+				</nav>
+				<?r
+			end
+		?>
 	</div>
-	<script src="/_static/sidebar.js"></script>
 </content:page>

data/pages/releases/index.xnode

@@ -7,7 +7,6 @@
 		<div class="content">
 			#{Markup.raw document.to_html}
 		</div>
-		<script src="/_static/sidebar.js"></script>
 	</content:page>
 <?r else ?>
 	<content:page>

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);
+		}
 	});
-});
+}