@fuzdev/fuz_code 0.46.0 → 0.46.2

package/src/lib/range_highlighting.svelte.ts

@@ -0,0 +1,100 @@
+import {onDestroy} from 'svelte';
+import {DEV} from 'esm-env';
+
+import type {SyntaxStyler, SyntaxGrammar} from './syntax_styler.js';
+import {HighlightManager, supports_css_highlight_api} from './highlight_manager.js';
+
+/**
+ * Reactive inputs for `create_range_highlighting`. All values are getters so the
+ * helper can track the consuming component's reactive state across the call
+ * boundary (the Svelte 5 getter-injection pattern).
+ */
+export interface RangeHighlightingOptions {
+	/** The element whose first text node receives the highlight ranges. */
+	element: () => Element | undefined;
+	/**
+	 * The text to tokenize. Must match the element's text node exactly (e.g. a
+	 * textarea backdrop includes its trailing newline here too).
+	 */
+	text: () => string;
+	/** Language id; `null` disables highlighting. */
+	lang: () => string | null;
+	/** Optional custom grammar; takes precedence over `lang` for tokenization. */
+	grammar: () => SyntaxGrammar | undefined;
+	/** The syntax styler whose registered grammars back `lang` lookups. */
+	syntax_styler: () => SyntaxStyler;
+	/** Extra gate — ranges are only applied when this returns true. Defaults to always-on. */
+	enabled?: () => boolean;
+	/** Component name used in DEV warnings. */
+	dev_label: string;
+}
+
+/** Reactive outputs from `create_range_highlighting`. */
+export interface RangeHighlighting {
+	readonly highlighting_disabled: boolean;
+}
+
+/**
+ * Wires up CSS Custom Highlight API range highlighting for a single element's
+ * text node, shared by `CodeHighlight` and `CodeTextarea`. Creates a
+ * `HighlightManager`, memoizes tokenization, applies/clears ranges in an effect,
+ * emits DEV warnings for unsupported languages, and tears down on destroy.
+ *
+ * Must be called during component initialization (it uses `$effect`/`onDestroy`).
+ */
+export const create_range_highlighting = (options: RangeHighlightingOptions): RangeHighlighting => {
+	const manager = supports_css_highlight_api() ? new HighlightManager() : null;
+	const is_enabled = options.enabled ?? (() => true);
+
+	const language_supported = $derived(
+		options.lang() !== null && !!options.syntax_styler().langs[options.lang()!],
+	);
+	const highlighting_disabled = $derived(
+		options.lang() === null || (!language_supported && !options.grammar()),
+	);
+
+	// tokenize once per (text, grammar, lang) change -- memoized so unrelated
+	// reactivity doesn't trigger a full re-tokenization
+	const range_tokens = $derived.by(() => {
+		if (!manager || !is_enabled() || highlighting_disabled) return null;
+		const text = options.text();
+		if (!text) return null;
+		// route through the styler so `before_tokenize`/`after_tokenize` hooks run,
+		// matching `stylize`'s HTML path; `grammar` undefined falls back to the
+		// registered lang grammar (`! safe bc of `highlighting_disabled`)
+		return options.syntax_styler().tokenize(text, options.lang()!, options.grammar());
+	});
+
+	if (manager) {
+		$effect(() => {
+			const element = options.element();
+			if (!element || !range_tokens) {
+				manager.clear_element_ranges();
+				return;
+			}
+			manager.highlight_from_syntax_tokens(element, range_tokens);
+		});
+	}
+
+	if (DEV) {
+		$effect(() => {
+			// a lang was requested but we can't highlight it (unknown id, no grammar)
+			if (options.lang() && highlighting_disabled) {
+				const langs = Object.keys(options.syntax_styler().langs).join(', ');
+				// eslint-disable-next-line no-console
+				console.error(
+					`[${options.dev_label}] Language "${options.lang()}" is not supported and no custom grammar provided. ` +
+						`Highlighting disabled. Supported: ${langs}`,
+				);
+			}
+		});
+	}
+
+	onDestroy(() => manager?.destroy());
+
+	return {
+		get highlighting_disabled() {
+			return highlighting_disabled;
+		},
+	};
+};

package/src/lib/syntax_styler.ts

@@ -3,6 +3,13 @@ import {tokenize_syntax} from './tokenize_syntax.js';
 
 export type AddSyntaxGrammar = (syntax_styler: SyntaxStyler) => void;
 
+/**
+ * Maps a matched `&`, `<`, or non-breaking space in text content to its
+ * HTML-safe form. Used as the replacer in `stringify_token` for leaf strings
+ * (non-breaking spaces are normalized to a regular space).
+ */
+const escape_text_char = (ch: string): string => (ch === '&' ? '&amp;' : ch === '<' ? '&lt;' : ' ');
+
 /**
  * Based on Prism (https://github.com/PrismJS/prism)
  * by Lea Verou (https://lea.verou.me/)
@@ -127,7 +134,42 @@ export class SyntaxStyler {
 		lang: string,
 		grammar: SyntaxGrammar | undefined = this.get_lang(lang),
 	): string {
-		var ctx: HookBeforeTokenizeCallbackContext = {
+		// stringify with the post-hook `lang`, which a `before_tokenize` hook may
+		// have rewritten (it flows into each token's `wrap` hook context)
+		const c = this.#tokenize_hooked(text, lang, grammar);
+		return this.stringify_token(c.tokens, c.lang);
+	}
+
+	/**
+	 * Tokenizes `text` into a `SyntaxTokenStream`, running the `before_tokenize`
+	 * and `after_tokenize` hooks. This is the tokenization half of `stylize` — use
+	 * it when you need the token stream itself (e.g. CSS Custom Highlight API range
+	 * highlighting) rather than HTML.
+	 *
+	 * @param text - source to tokenize
+	 * @param lang - language identifier; passed to the tokenize hooks
+	 * @param grammar - grammar to tokenize with; defaults to `this.get_lang(lang)`
+	 * @returns the resulting token stream
+	 */
+	tokenize(
+		text: string,
+		lang: string,
+		grammar: SyntaxGrammar | undefined = this.get_lang(lang),
+	): SyntaxTokenStream {
+		return this.#tokenize_hooked(text, lang, grammar).tokens;
+	}
+
+	/**
+	 * Runs `before_tokenize` → `tokenize_syntax` → `after_tokenize`, returning the
+	 * resolved context. Shared by `stylize` (which also needs the post-hook `lang`)
+	 * and `tokenize` (which only needs `tokens`).
+	 */
+	#tokenize_hooked(
+		text: string,
+		lang: string,
+		grammar: SyntaxGrammar,
+	): HookAfterTokenizeCallbackContext {
+		const ctx: HookBeforeTokenizeCallbackContext = {
 			code: text,
 			grammar,
 			lang,
@@ -137,7 +179,7 @@ export class SyntaxStyler {
 		const c = ctx as any as HookAfterTokenizeCallbackContext;
 		c.tokens = tokenize_syntax(c.code, c.grammar);
 		this.run_hook_after_tokenize(c);
-		return this.stringify_token(c.tokens, c.lang);
+		return c;
 	}
 
 	/**
@@ -263,10 +305,9 @@ export class SyntaxStyler {
 	 */
 	stringify_token(o: string | SyntaxToken | SyntaxTokenStream, lang: string): string {
 		if (typeof o === 'string') {
-			return o
-				.replace(/&/g, '&amp;')
-				.replace(/</g, '&lt;')
-				.replace(/\u00a0/g, ' ');
+			// single pass over the leaf text (only `&` and `<` need escaping in text
+			// content; `\u00a0` is normalized to a regular space)
+			return o.replace(/[&<\u00a0]/g, escape_text_char);
 		}
 		if (Array.isArray(o)) {
 			var s = '';
@@ -276,21 +317,29 @@ export class SyntaxStyler {
 			return s;
 		}
 
+		var content = this.stringify_token(o.content, lang);
+
+		// build the class list once; aliases are always an array after normalization
+		var classes = `token_${o.type}`;
+		for (const a of o.alias) {
+			classes += ` token_${a}`;
+		}
+
+		// fast path: with no `wrap` hooks the tag is always a plain <span> with no
+		// attributes, so skip the per-token context object and hook dispatch
+		if (this.hooks_wrap.length === 0) {
+			return '<span class="' + classes + '">' + content + '</span>';
+		}
+
 		var ctx: HookWrapCallbackContext = {
 			type: o.type,
-			content: this.stringify_token(o.content, lang),
+			content,
 			tag: 'span',
-			classes: [`token_${o.type}`],
+			classes: classes.split(' '),
 			attributes: {},
 			lang,
 		};
 
-		var aliases = o.alias;
-		// alias is always an array after normalization
-		for (const a of aliases) {
-			ctx.classes.push(`token_${a}`);
-		}
-
 		this.run_hook_wrap(ctx);
 
 		var attributes = '';