utopia-project 0.37.6 → 0.38.0

data/public/_components/@socketry/syntax/Syntax/Rule.js

@@ -0,0 +1,306 @@
+import {Match} from './Match.js';
+import {Language} from './Language.js';
+
+export class Rule {
+	/**
+	 * Convert string to token pattern with word boundaries.
+	 */
+	static convertStringToTokenPattern(pattern, escape) {
+		let prefix = '\\b',
+			postfix = '\\b';
+
+		if (!pattern.match(/^\w/)) {
+			if (!pattern.match(/\w$/)) {
+				prefix = postfix = '';
+			} else {
+				prefix = '\\B';
+			}
+		} else {
+			if (!pattern.match(/\w$/)) {
+				postfix = '\\B';
+			}
+		}
+
+		if (escape) {
+			pattern = pattern.replace(/[\-\[\]{}()*+?.\\\^$|,#\s]/g, '\\$&');
+		}
+
+		return prefix + pattern + postfix;
+	}
+
+	/**
+	 * Normalize a rule by converting string patterns to RegExp and setting defaults.
+	 */
+	static normalizeRule(rule, owner) {
+		const normalized = {...rule, owner};
+
+		if (typeof normalized.pattern === 'string') {
+			normalized.string = normalized.pattern;
+			normalized.pattern = new RegExp(
+				Rule.convertStringToTokenPattern(normalized.string, true),
+				normalized.options
+			);
+		}
+
+		// Default pattern extraction algorithm
+		normalized.apply = normalized.apply || Rule.matchPattern;
+
+		return normalized;
+	}
+
+	/**
+	 * Match a pattern against text and return matches.
+	 */
+	static async matchPattern(syntax, rule, text) {
+		if (!rule.pattern) {
+			return [];
+		}
+
+		const matches = [];
+
+		// Duplicate the pattern and ensure 'g' flag is set:
+		let pattern = rule.pattern;
+		if (!pattern.global) {
+			pattern = new RegExp(pattern.source, pattern.flags + 'g');
+		}
+
+		let match;
+		while ((match = pattern.exec(text)) !== null) {
+			if (rule.matches) {
+				// Try new signature first (syntax, match, rule), fall back to old signature (match, rule)
+				// This supports both extractMatches (new) and custom matches functions (old)
+				const result =
+					rule.matches.length >= 3
+						? rule.matches(syntax, match, rule)
+						: rule.matches(match, rule);
+				// Handle both sync and async matches functions
+				matches.push(...(result instanceof Promise ? await result : result));
+			} else if (rule.language) {
+				// Use the owning language's syntax to build sub-tree for embedded language
+				matches.push(
+					await Language.buildTree(syntax, rule, match[0], match.index, undefined)
+				);
+			} else {
+				matches.push(new Match(match.index, match[0].length, rule, match[0]));
+			}
+			if (rule.incremental) {
+				// Don't start scanning from the end of the match
+				pattern.lastIndex = match.index + 1;
+			}
+		}
+		return matches;
+	}
+
+	/**
+	 * Create a matches extractor based on capture groups.
+	 * Each provided rule corresponds to a capture group (default i+1) in the RegExp match.
+	 * If a rule has {language: 'name'}, a subtree will be built using that language.
+	 * If a rule has other expression fields (e.g. type), a Match will be created.
+	 */
+	static extractMatches(...rules) {
+		return async function (syntax, match, expression) {
+			const results = [];
+			for (let i = 0; i < rules.length; i += 1) {
+				const rule = rules[i];
+				// Skip null/undefined rules:
+				if (rule == null) continue;
+
+				// Determine the capture group index to use:
+				let index = typeof rule.index !== 'undefined' ? rule.index : i + 1;
+				const value = match[index];
+
+				// Skip empty captures:
+				if (!value || value.length === 0) continue;
+
+				// Compute absolute offset of this capture group within the full match:
+				const offset = match.index + match[0].indexOf(value);
+
+				// Create either a subtree or a Match based on the rule:
+				if (rule.language) {
+					results.push(
+						await Language.buildTree(syntax, rule, value, offset, undefined)
+					);
+				} else {
+					const nestedExpression = {owner: expression?.owner, ...rule};
+					results.push(new Match(offset, value.length, nestedExpression, value));
+				}
+			}
+
+			return results;
+		};
+	}
+
+	/**
+	 * Create a conditional matcher that selects a rule based on another capture group.
+	 * Tests a condition capture group against patterns to determine which rule to apply
+	 * to a content capture group.
+	 * 
+	 * @param {number} conditionIndex - Capture group index to test against patterns
+	 * @param {number} contentIndex - Capture group index containing content to match
+	 * @param {Array<{pattern?: RegExp, ...rule}>} conditions - Array of condition objects. Each can have:
+	 *   - pattern: RegExp to test against the condition group (optional - if omitted, acts as fallback)
+	 *   - Any rule properties (language, type, etc.) to apply when pattern matches
+	 * @returns {Function} A matches function for use in language rules
+	 * 
+	 * @example
+	 * // Script tags with type-based language selection
+	 * language.push({
+	 *   pattern: /<script(\s+[^>]*?)?>((.|\n)*?)<\/script>/im,
+	 *   matches: Rule.extractConditionalMatch(1, 2, [
+	 *     {pattern: /type\s*=\s*["']importmap["']/i, language: 'json'},
+	 *     {pattern: /type\s*=\s*["'](?:text|application)\/javascript["']/i, language: 'javascript'},
+	 *     {language: 'javascript'} // Fallback for no type or unknown types
+	 *   ])
+	 * });
+	 * 
+	 * @example
+	 * // Code fence with language specifier
+	 * language.push({
+	 *   pattern: /```(\w+)?\n([\s\S]*?)```/,
+	 *   matches: Rule.extractConditionalMatch(1, 2, [
+	 *     {pattern: /^javascript$/i, language: 'javascript'},
+	 *     {pattern: /^python$/i, language: 'python'},
+	 *     {language: 'plaintext'} // Fallback
+	 *   ])
+	 * });
+	 * 
+	 * @example
+	 * // Conditional type based on prefix
+	 * language.push({
+	 *   pattern: /(TODO|FIXME|NOTE):\s*(.+)/,
+	 *   matches: Rule.extractConditionalMatch(1, 2, [
+	 *     {pattern: /^TODO$/i, type: 'todo'},
+	 *     {pattern: /^FIXME$/i, type: 'error'},
+	 *     {pattern: /^NOTE$/i, type: 'comment'}
+	 *   ])
+	 * });
+	 */
+	static extractConditionalMatch(conditionIndex, contentIndex, conditions) {
+		return async function (syntax, match, expression) {
+			const condition = match[conditionIndex] || '';
+			const content = match[contentIndex];
+
+			// Skip if no content
+			if (!content) return [];
+
+			// Find matching rule
+			let rule = null;
+			for (const candidate of conditions) {
+				// If no pattern specified, it's a fallback
+				if (!candidate.pattern || candidate.pattern.test(condition)) {
+					rule = candidate;
+					break;
+				}
+			}
+
+			// If no rule determined, return empty
+			if (!rule) return [];
+
+			// Extract rule properties (exclude pattern)
+			const {pattern, ...ruleProps} = rule;
+
+			// Build syntax tree or create match based on rule properties
+			const offset = match.index + match[0].indexOf(content);
+			
+			if (ruleProps.language) {
+				return [
+					await Language.buildTree(
+						syntax,
+						{...ruleProps, owner: expression?.owner},
+						content,
+						offset,
+						undefined
+					)
+				];
+			} else {
+				const nestedExpression = {owner: expression?.owner, ...ruleProps};
+				return [new Match(offset, content.length, nestedExpression, content)];
+			}
+		};
+	}
+
+	static cStyleComment = {
+		pattern: /\/\*[\s\S]*?\*\//m,
+		type: 'comment',
+		allow: ['href']
+	};
+	static cppStyleComment = {
+		pattern: /\/\/.*$/m,
+		type: 'comment',
+		allow: ['href']
+	};
+	static perlStyleComment = {
+		pattern: /#.*$/m,
+		type: 'comment',
+		allow: ['href']
+	};
+
+	static perlStyleRegularExpression = {
+		pattern: /\B\/([^\\\/]|\\.)*\/[a-z]*(?=\s*($|[^\w\s'"\(]))/m,
+		type: 'constant',
+		incremental: true
+	};
+	static rubyStyleRegularExpression = {
+		pattern: /\B\/([^\\\/]|\\.)*\/[a-z]*(?=\s*($|[^\w\s'"\(]|do))/m,
+		type: 'constant',
+		incremental: true
+	};
+
+	static cStyleFunction = {
+		pattern: /([a-z_][a-z0-9_]*)\s*\(/i,
+		matches: this.extractMatches({type: 'function'})
+	};
+	static camelCaseType = {pattern: /\b_*[A-Z][\w]*\b/, type: 'type'};
+	static cStyleType = {pattern: /\b[_a-z][_\w]*_t\b/i, type: 'type'};
+
+	static xmlComment = {
+		pattern: /(&lt;|<)!--[\s\S]*?--(&gt;|>)/m,
+		type: 'comment'
+	};
+	static webLink = {pattern: /\w+:\/\/[\w\-.\/?%&=@:;#]*/, type: 'href'};
+
+	static hexNumber = {pattern: /\b0x[0-9a-fA-F]+/, type: 'constant'};
+	static decimalNumber = {
+		pattern: /\b[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?/,
+		type: 'constant'
+	};
+
+	static doubleQuotedString = {pattern: /"([^\\"\n]|\\.)*"/, type: 'string'};
+	static singleQuotedString = {pattern: /'([^\\'\n]|\\.)*'/, type: 'string'};
+	static multiLineDoubleQuotedString = {
+		pattern: /"([^\\"]|\\.)*"/,
+		type: 'string'
+	};
+	static multiLineSingleQuotedString = {
+		pattern: /'([^\\']|\\.)*'/,
+		type: 'string'
+	};
+	static stringEscape = {pattern: /\\./, type: 'escape', only: ['string']};
+
+	/**
+	 * Create a process function that wraps matched tokens in documentation links.
+	 *
+	 * @param {string} baseUrl - The base URL for documentation lookups
+	 * @returns {Function} A process function for language.processes
+	 *
+	 * @example
+	 * language.processes['function'] = Rule.webLinkProcess('http://docs.python.org/search.html?q=');
+	 */
+	static webLinkProcess(baseUrl) {
+		return function (container, match, options) {
+			// Replace the span with an anchor element
+			const anchor = document.createElement('a');
+
+			// Copy className and content from container
+			anchor.className = container.className;
+			anchor.innerHTML = container.innerHTML;
+
+			// Append the matched text to the base URL
+			anchor.href = `${baseUrl}${encodeURIComponent(match.value)}`;
+
+			return anchor;
+		};
+	}
+}
+
+export default Rule;

data/public/_components/@socketry/syntax/Syntax.js

@@ -0,0 +1,356 @@
+/**
+ * Syntax - Core highlighting engine
+ * A modern, framework-agnostic syntax highlighter
+ *
+ * @package @socketry/syntax
+ * @author Samuel G. D. Williams
+ * @license MIT
+ */
+
+import {Loader} from './Syntax/Loader.js';
+import {
+	LanguageNotFoundError,
+	LanguageLoadError,
+	StyleSheetLoadError
+} from './Syntax/Errors.js';
+
+export class Syntax {
+	static #default = null;
+
+	#root = null;
+	#aliases = {};
+	#languages = new Loader((loader, name) => this.#loadLanguage(loader, name));
+	#styleSheets = new Loader((loader, url) => this.#loadStyleSheet(loader, url));
+	#styles = {};
+	#themes = {};
+	#themeRoot = null; // Base URL for theme assets (CSS)
+
+	#defaultOptions = {
+		theme: 'base',
+		linkify: true,
+		strict: false
+	};
+
+	/**
+	 * Get or create the default Syntax instance
+	 */
+	static get default() {
+		if (!this.#default) {
+			this.#default = new Syntax();
+		}
+		return this.#default;
+	}
+
+	/**
+	 * Set a custom default Syntax instance
+	 */
+	static set default(instance) {
+		this.#default = instance;
+	}
+
+	/**
+	 * Detect the default root path for loading language modules
+	 * Uses import.meta.url to reliably locate the Syntax module directory
+	 */
+	static detectRoot() {
+		try {
+			const url = new URL('./', import.meta.url);
+			return url.href;
+		} catch (error) {
+			// Fallback: try document.currentScript (may not work reliably)
+			if (
+				typeof document !== 'undefined' &&
+				document.currentScript &&
+				document.currentScript.src
+			) {
+				const url = new URL(document.currentScript.src);
+				return url.pathname.substring(0, url.pathname.lastIndexOf('/') + 1);
+			}
+			// Last resort fallback
+			return '/';
+		}
+	}
+
+	/**
+	 * Initialize syntax highlighting on the page
+	 * Registers the web component and sets up the default syntax instance
+	 * Languages will be auto-loaded on demand when referenced by elements
+	 *
+	 * @param {Object} options - Configuration options
+	 * @param {Syntax} options.syntax - Syntax instance to use (defaults to Syntax.default)
+	 * @param {boolean} options.upgradeAll - Whether to automatically upgrade existing elements (default: true)
+	 * @param {string} options.selector - CSS selector for upgrading (default: 'code[class*="language-"]')
+	 * @param {string} options.root - Base URL for loading language modules (default: auto-detected)
+	 * @returns {Promise<void>}
+	 */
+	static async highlight(options = {}) {
+		const {
+			syntax = Syntax.default,
+			upgradeAll: shouldUpgradeAll = true,
+			selector = 'code[class*="language-"]',
+			root = null
+		} = options;
+
+		// Set the default syntax instance:
+		Syntax.default = syntax;
+
+		// Configure root for auto-loading if provided:
+		if (root && !syntax.root) {
+			syntax.root = root;
+		}
+
+		// Import and register the web component:
+		const {CodeElement, upgradeAll} = await import('./Syntax/CodeElement.js');
+
+		if (!customElements.get('syntax-code')) {
+			customElements.define('syntax-code', CodeElement);
+		}
+
+		// Upgrade existing code blocks if requested:
+		if (shouldUpgradeAll) {
+			if (upgradeAll) {
+				// Use the upgradeAll function with the selector:
+				upgradeAll(selector, syntax);
+			} else {
+				// Fallback to customElements.upgrade if the function isn't available:
+				customElements.upgrade(document.body);
+			}
+		}
+	}
+
+	constructor(options = {}) {
+		// Allow customization via constructor options
+		if (options.root !== undefined) this.#root = options.root;
+		if (options.theme !== undefined) this.#defaultOptions.theme = options.theme;
+		if (options.themeRoot !== undefined) this.#themeRoot = options.themeRoot;
+
+		// Set default root if not provided
+		if (this.#root === null) {
+			this.#root = Syntax.detectRoot();
+		}
+	}
+
+	// Public getters for commonly accessed properties
+	get defaultOptions() {
+		return this.#defaultOptions;
+	}
+
+	get languages() {
+		return this.#languages;
+	}
+
+	get aliases() {
+		return this.#aliases;
+	}
+
+	get styles() {
+		return this.#styles;
+	}
+
+	get themes() {
+		return this.#themes;
+	}
+
+	// Theme root for CSS assets
+	get themeRoot() {
+		return this.#resolveThemeRoot().toString();
+	}
+
+	set themeRoot(value) {
+		this.#themeRoot = value;
+		// Clear the stylesheet cache when theme changes
+		this.#styleSheets.clear();
+	}
+
+	get root() {
+		return this.#root;
+	}
+
+	set root(value) {
+		this.#root = value;
+	}
+
+	/**
+	 * Resolve the base URL for the current theme's assets.
+	 * Priority:
+	 * 1) Explicit options.themeRoot or setter
+	 * 2) Relative to this module location: ./themes/<theme>/
+	 */
+	#resolveThemeRoot() {
+		try {
+			if (this.#themeRoot) {
+				return new URL(
+					this.#themeRoot,
+					typeof document !== 'undefined' ? document.baseURI : import.meta.url
+				);
+			}
+			// Default to a folder next to Syntax.js
+			return new URL(`./themes/${this.#defaultOptions.theme}/`, import.meta.url);
+		} catch (error) {
+			// As a last resort, fall back to root if provided or current location:
+			const base =
+				this.#root || (typeof location !== 'undefined' ? location.href : '');
+			return new URL(`themes/${this.#defaultOptions.theme}/`, base);
+		}
+	}
+
+	/**
+	 * Fetch CSS for use in Shadow DOM
+	 * Returns an object with {sheet, cssText} where sheet is a CSSStyleSheet (if supported)
+	 * The result is cached and deduplicated across calls
+	 */
+	async getStyleSheet(url) {
+		return this.#styleSheets.load(url);
+	}
+
+	/**
+	 * Load a stylesheet from a URL
+	 * Used internally by the stylesheet loader
+	 */
+	async #loadStyleSheet(loader, url) {
+		const response = await fetch(url);
+		if (!response.ok) {
+			throw new StyleSheetLoadError(url.toString(), response.status);
+		}
+		const cssText = await response.text();
+
+		// If CSSStyleSheet constructor is available, create and return a stylesheet:
+		if (typeof CSSStyleSheet !== 'undefined') {
+			const sheet = new CSSStyleSheet();
+			await sheet.replace(cssText);
+			return {sheet, cssText};
+		}
+
+		// Otherwise just return the text:
+		return {cssText};
+	}
+
+	/**
+	 * Load a language module from disk/network
+	 * Used internally by the language loader
+	 */
+	async #loadLanguage(loader, name) {
+		const path = `${this.#root}Syntax/Language/${name}.js`;
+		let module;
+		try {
+			module = await import(path);
+		} catch (error) {
+			throw new LanguageLoadError(name, path, {cause: error});
+		}
+		
+		// If the module exports a register function, call it with this instance
+		if (typeof module.default === 'function') {
+			module.default(this);
+		}
+		
+		// After calling register, aliases have been registered. Re-resolve the name:
+		let resolvedName = this.#aliases[name] || name;
+		return loader.get(resolvedName);
+	}
+
+	/**
+	 * Load a language module dynamically
+	 */
+	async getResource(name) {
+		// First check if the language is already loaded (including via alias)
+		const resolvedName = this.#aliases[name] || name;
+		if (this.#languages.has(resolvedName)) {
+			return this.#languages.get(resolvedName);
+		}
+
+		// Use the loader to deduplicate concurrent loads
+		return this.#languages.load(resolvedName);
+	}
+
+	/**
+	 * Register language aliases
+	 */
+	alias(name, aliases) {
+		this.#aliases[name] = name;
+
+		for (const alias of aliases) {
+			this.#aliases[alias] = name;
+		}
+	}
+
+	/**
+	 * Register a language with this Syntax instance
+	 */
+	register(name, language) {
+		// Store directly in the loader's cache using the new set() method
+		this.#languages.set(name, language);
+
+		// Also store in aliases if not already there
+		if (!this.#aliases[name]) {
+			this.#aliases[name] = name;
+		}
+
+		return language;
+	}
+
+	/**
+	 * Get a language by name or alias
+	 * Auto-loads the language if not already registered
+	 */
+	async getLanguage(name) {
+		// Resolve alias
+		const resolvedName = (this.#aliases[name] || name).toLowerCase();
+
+		// If already loaded, return it
+		if (this.#languages.has(resolvedName)) {
+			return this.#languages.get(resolvedName);
+		}
+
+		// Otherwise, try to load it
+		try {
+			return await this.getResource(name);
+		} catch (error) {
+			if (this.#defaultOptions.strict && !(error instanceof LanguageLoadError)) {
+				// If strict and not a load error, ensure a consistent error type:
+				throw new LanguageNotFoundError(resolvedName, {cause: error});
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Check if a language is already registered (synchronous)
+	 */
+	hasLanguage(name) {
+		// Resolve alias
+		const resolvedName = this.#aliases[name] || name;
+		return this.#languages.has(resolvedName);
+	}
+
+	/**
+	 * Get all aliases for a language
+	 */
+	languageAliases(language) {
+		const aliases = [];
+
+		for (const [name, target] of Object.entries(this.#aliases)) {
+			if (target === language) {
+				aliases.push(name);
+			}
+		}
+
+		return aliases;
+	}
+
+	/**
+	 * Get all language names (primary names, not aliases)
+	 */
+	languageNames() {
+		const names = [];
+
+		for (const [name, target] of Object.entries(this.#aliases)) {
+			if (name === target) {
+				names.push(name);
+			}
+		}
+
+		return names;
+	}
+}
+
+export default Syntax;

data/public/_components/@socketry/syntax/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.