@fuzdev/fuz_code 0.45.0 → 0.46.0

package/src/lib/grammar_markdown.ts

@@ -16,7 +16,7 @@ interface FenceType {
 }
 
 /**
- * Helper to create fenced code block pattern for a language
+ * Helper to create fenced code block pattern for a language.
  */
 const create_fence_pattern = (
 	backticks: string,
@@ -48,7 +48,7 @@ const create_fence_pattern = (
 };
 
 /**
- * Helper to create catch-all fence pattern (unknown languages)
+ * Helper to create catch-all fence pattern (unknown languages).
  */
 const create_catchall_fence = (backticks: string): SyntaxGrammarTokenRaw => {
 	const pattern = new RegExp(`^${backticks}[^\\n\\r]*(?:\\r?\\n|\\r)[\\s\\S]*?^${backticks}$`, 'm');
@@ -67,7 +67,7 @@ const create_catchall_fence = (backticks: string): SyntaxGrammarTokenRaw => {
 };
 
 /**
- * Helper to create md self-reference placeholder pattern
+ * Helper to create md self-reference placeholder pattern.
  */
 const create_md_placeholder = (backticks: string): SyntaxGrammarTokenRaw => {
 	const pattern = new RegExp(
@@ -103,6 +103,7 @@ export const add_grammar_markdown: AddSyntaxGrammar = (syntax_styler) => {
 		{aliases: ['html', 'markup'], id: 'markup'},
 		{aliases: ['json'], id: 'json'},
 		{aliases: ['svelte'], id: 'svelte'},
+		{aliases: ['bash', 'sh', 'shell'], id: 'bash'},
 	];
 
 	// Fence types: higher counts first (for proper precedence in tokenization)

package/src/lib/grammar_markup.ts

@@ -98,9 +98,10 @@ export const add_grammar_markup: AddSyntaxGrammar = (syntax_styler) => {
  *
  * An example of an inlined language is CSS with `<style>` tags.
  *
- * @param tag_name - The name of the tag that contains the inlined language. This name will be treated as
- * case insensitive.
- * @param lang - The language key.
+ * @param syntax_styler - the `SyntaxStyler` instance to modify
+ * @param tag_name - the name of the tag that contains the inlined language, treated as case insensitive
+ * @param lang - the language key
+ * @param inside_lang - the language to insert into, defaults to `'markup'`
  */
 export const grammar_markup_add_inlined = (
 	syntax_styler: SyntaxStyler,
@@ -145,13 +146,13 @@ export const grammar_markup_add_inlined = (
 };
 
 /**
- * Adds an pattern to style languages embedded in HTML attributes.
+ * Adds a pattern to style languages embedded in HTML attributes.
  *
  * An example of an inlined language is CSS with `style` attributes.
  *
- * @param attr_name - The name of the tag that contains the inlined language. This name will be treated as
- * case insensitive.
- * @param lang - The language key.
+ * @param syntax_styler - the `SyntaxStyler` instance to modify
+ * @param attr_name - the name of the attribute that contains the inlined language, treated as case insensitive
+ * @param lang - the language key
  */
 export const grammar_markup_add_attribute = (
 	syntax_styler: SyntaxStyler,

package/src/lib/highlight_manager.ts

@@ -4,16 +4,16 @@ import {highlight_priorities} from './highlight_priorities.js';
 export type HighlightMode = 'auto' | 'ranges' | 'html';
 
 /**
- * Check for CSS Highlights API support.
+ * Checks for CSS Highlights API support.
  */
 export const supports_css_highlight_api = (): boolean =>
-	!!(globalThis.CSS?.highlights && globalThis.Highlight); // eslint-disable-line @typescript-eslint/no-unnecessary-condition
+	!!(globalThis.CSS?.highlights && globalThis.Highlight);
 
 /**
  * Manages CSS Custom Highlight API ranges for a single element.
  * Tracks ranges per element and only removes its own ranges when clearing.
  *
- * **Experimental** — limited browser support. Use `Code` for production.
+ * **Experimental** — limited browser support. Use `Code.svelte` for production.
  *
  * @example
  * ```ts
@@ -32,7 +32,7 @@ export class HighlightManager {
 	}
 
 	/**
-	 * Highlight from syntax styler token stream.
+	 * Highlights from a `SyntaxTokenStream` produced by `tokenize_syntax`.
 	 */
 	highlight_from_syntax_tokens(element: Element, tokens: SyntaxTokenStream): void {
 		// Find the text node (it might not be firstChild due to Svelte comment nodes)
@@ -85,7 +85,7 @@ export class HighlightManager {
 	}
 
 	/**
-	 * Clear only this element's ranges from highlights.
+	 * Clears only this element's ranges from highlights.
 	 */
 	clear_element_ranges(): void {
 		for (const [name, ranges] of this.element_ranges) {
@@ -111,7 +111,7 @@ export class HighlightManager {
 	}
 
 	/**
-	 * Create ranges for all tokens in the tree.
+	 * Creates ranges for all tokens in the tree.
 	 */
 	#create_all_ranges(
 		tokens: SyntaxTokenStream,

package/src/lib/svelte_preprocess_fuz_code.ts

@@ -23,15 +23,15 @@ export interface PreprocessFuzCodeOptions {
 	/** File patterns to exclude. */
 	exclude?: Array<string | RegExp>;
 
-	/** Custom syntax styler. @default syntax_styler_global */
+	/** Custom `SyntaxStyler` instance. @default syntax_styler_global */
 	syntax_styler?: SyntaxStyler;
 
 	/** Enable in-memory caching. @default true */
 	cache?: boolean;
 
 	/**
-	 * Import sources that resolve to the Code component.
-	 * Used to verify that `<Code>` in templates actually refers to fuz_code's Code.svelte.
+	 * Import sources that resolve to the `Code` component.
+	 * Used to verify that `<Code>` in templates actually refers to `Code.svelte`.
 	 *
 	 * @default ['@fuzdev/fuz_code/Code.svelte']
 	 */
@@ -48,7 +48,7 @@ export interface PreprocessFuzCodeOptions {
  * Svelte preprocessor that compiles static `Code` component content at build time,
  * replacing runtime syntax highlighting with pre-rendered HTML.
  *
- * @param options preprocessor configuration
+ * @param options - `PreprocessFuzCodeOptions` configuration
  * @returns a Svelte preprocessor group
  *
  * @example
@@ -141,7 +141,7 @@ interface FindCodeUsagesOptions {
 }
 
 /**
- * Attempt to highlight content, using cache if available.
+ * Attempts to highlight content, using cache if available.
  * Returns the highlighted HTML, or `null` on error.
  */
 const try_highlight = (
@@ -165,7 +165,7 @@ const try_highlight = (
 };
 
 /**
- * Walks the AST to find Code component usages with static `content` props
+ * Walks the AST to find `Code` component usages with static `content` props
  * and generates transformations to replace them with `dangerous_raw_html`.
  */
 const find_code_usages = (

package/src/lib/syntax_styler.ts

@@ -92,15 +92,14 @@ export class SyntaxStyler {
 	 * - Custom grammar: `stylize(code, 'ts', customGrammar)` - uses custom grammar but keeps 'ts' label
 	 * - Extended grammar: `stylize(code, 'custom', this.extend_grammar('ts', extension))` - new language variant
 	 *
-	 * @param text - The source code to syntax highlight.
-	 * @param lang - Language identifier (e.g., 'ts', 'css', 'html'). Used for:
-	 *   - Grammar lookup when `grammar` is undefined
-	 *   - Hook context (`lang` field passed to hooks)
-	 *   - Language identification in output
-	 * @param grammar - Optional custom grammar object. When undefined, automatically
-	 *   looks up the grammar via `this.get_lang(lang)`. Provide this to use a custom
-	 *   or modified grammar instead of the registered one.
-	 *
+	 * @param text - the source code to syntax highlight
+	 * @param lang - language identifier (e.g., 'ts', 'css', 'html'), used for:
+	 *   - grammar lookup when `grammar` is undefined
+	 *   - hook context (`lang` field passed to hooks)
+	 *   - language identification in output
+	 * @param grammar - optional custom `SyntaxGrammar` object; when undefined, automatically
+	 *   looks up the grammar via `this.get_lang(lang)`; provide this to use a custom
+	 *   or modified grammar instead of the registered one
 	 * @returns HTML string with syntax highlighting using CSS classes (`.token_*`)
 	 *
 	 * @example
@@ -158,7 +157,7 @@ export class SyntaxStyler {
 	 * };
 	 * ```
 	 *
-	 * then the `style` token will be added (and processed) at the end. `insert_before` allows you to insert tokens
+	 * then the `style` token will be added (and processed) at the end. `grammar_insert_before` allows you to insert tokens
 	 * before existing tokens. For the CSS example above, you would use it like this:
 	 *
 	 * ```js
@@ -185,12 +184,12 @@ export class SyntaxStyler {
 	 *
 	 * ## Limitations
 	 *
-	 * The main problem `insert_before` has to solve is iteration order. Since ES2015, the iteration order for object
+	 * The main problem `grammar_insert_before` has to solve is iteration order. Since ES2015, the iteration order for object
 	 * properties is guaranteed to be the insertion order (except for integer keys) but some browsers behave
-	 * differently when keys are deleted and re-inserted. So `insert_before` can't be implemented by temporarily
+	 * differently when keys are deleted and re-inserted. So `grammar_insert_before` can't be implemented by temporarily
 	 * deleting properties which is necessary to insert at arbitrary positions.
 	 *
-	 * To solve this problem, `insert_before` doesn't actually insert the given tokens into the target object.
+	 * To solve this problem, `grammar_insert_before` doesn't actually insert the given tokens into the target object.
 	 * Instead, it will create a new object and replace all references to the target object with the new one. This
 	 * can be done without temporarily deleting properties, so the iteration order is well-defined.
 	 *
@@ -205,16 +204,13 @@ export class SyntaxStyler {
 	 * assert(newMarkup === syntax_styler.get_lang('markup'));
 	 * ```
 	 *
-	 * @param inside - The property of `root` (e.g. a language id in `syntax_styler.langs`) that contains the
-	 * object to be modified.
-	 * @param before - The key to insert before.
-	 * @param insert - An object containing the key-value pairs to be inserted.
-	 * @param root - The object containing `inside`, i.e. the object that contains the
-	 * object to be modified.
-	 *
-	 * Defaults to `syntax_styler.langs`.
-	 *
-	 * @returns the new grammar object
+	 * @param inside - the property of `root` (e.g. a language id in `syntax_styler.langs`) that contains the
+	 * object to be modified
+	 * @param before - the key to insert before
+	 * @param insert - an object containing the key-value pairs to be inserted
+	 * @param root - the object containing `inside`, i.e. the object that contains the
+	 * object to be modified; defaults to `syntax_styler.langs`
+	 * @returns the new `SyntaxGrammar` object
 	 */
 	grammar_insert_before(
 		inside: string,
@@ -261,9 +257,9 @@ export class SyntaxStyler {
 	 *
 	 * Runs the `wrap` hook on each `SyntaxToken`.
 	 *
-	 * @param o - The token or token stream to be converted.
-	 * @param lang - The name of current language.
-	 * @returns The HTML representation of the token or token stream.
+	 * @param o - the token or `SyntaxTokenStream` to be converted
+	 * @param lang - the name of current language
+	 * @returns HTML representation of the token or token stream
 	 */
 	stringify_token(o: string | SyntaxToken | SyntaxTokenStream, lang: string): string {
 		if (typeof o === 'string') {
@@ -332,9 +328,9 @@ export class SyntaxStyler {
 	 * Therefore, it is encouraged to order overwriting tokens according to the positions of the overwritten tokens.
 	 * Furthermore, all non-overwriting tokens should be placed after the overwriting ones.
 	 *
-	 * @param base_id - The id of the language to extend. This has to be a key in `syntax_styler.langs`.
-	 * @param extension - The new tokens to append.
-	 * @returns the new grammar
+	 * @param base_id - the id of the language to extend, must be a key in `syntax_styler.langs`
+	 * @param extension - the new tokens to append
+	 * @returns the new `SyntaxGrammar`
 	 */
 	extend_grammar(base_id: string, extension: SyntaxGrammarRaw): SyntaxGrammar {
 		// Merge normalized base with un-normalized extension
@@ -346,7 +342,7 @@ export class SyntaxStyler {
 	}
 
 	/**
-	 * Normalize a single pattern to have consistent shape.
+	 * Normalizes a single pattern to have consistent shape.
 	 * This ensures all patterns have the same object shape for V8 optimization.
 	 */
 	#normalize_pattern(
@@ -387,15 +383,15 @@ export class SyntaxStyler {
 	}
 
 	/**
-	 * Normalize a grammar to have consistent object shapes.
+	 * Normalizes a grammar to have consistent object shapes.
 	 * This performs several optimizations:
-	 * 1. Merges `rest` property into main grammar
-	 * 2. Ensures all pattern values are arrays
-	 * 3. Normalizes all pattern objects to have consistent shapes
-	 * 4. Adds global flag to greedy patterns
+	 * 1. Merges `rest` property into main grammar.
+	 * 2. Ensures all pattern values are arrays.
+	 * 3. Normalizes all pattern objects to have consistent shapes.
+	 * 4. Adds global flag to greedy patterns.
 	 *
 	 * This is called once at registration time to avoid runtime overhead.
-	 * @param visited - Set of grammar object IDs already normalized (for circular references)
+	 * @param visited - set of grammar object IDs already normalized (for circular references)
 	 */
 	#normalize_grammar(grammar: SyntaxGrammarRaw, visited: Set<number>): void {
 		// Check if we've already normalized this grammar (circular reference)
@@ -510,14 +506,14 @@ export interface SyntaxGrammarTokenRaw {
 	 */
 	alias?: string | Array<string>;
 	/**
-	 * The nested grammar of this token.
+	 * The nested `SyntaxGrammarRaw` of this token.
 	 */
 	inside?: SyntaxGrammarRaw | null;
 }
 
 /**
  * Grammar token with all properties required.
- * This is the normalized representation used at runtime.
+ * This is the normalized representation of `SyntaxGrammarTokenRaw` used at runtime.
  */
 export interface SyntaxGrammarToken {
 	pattern: RegExp;
@@ -529,7 +525,7 @@ export interface SyntaxGrammarToken {
 
 /**
  * A grammar after normalization.
- * All values are arrays of normalized tokens with consistent shapes.
+ * All values are arrays of normalized `SyntaxGrammarToken` with consistent shapes.
  */
 export type SyntaxGrammar = Record<string, Array<SyntaxGrammarToken>>;
 

package/src/lib/syntax_styler_global.ts

@@ -6,6 +6,7 @@ import {add_grammar_js} from './grammar_js.js';
 import {add_grammar_ts} from './grammar_ts.js';
 import {add_grammar_svelte} from './grammar_svelte.js';
 import {add_grammar_json} from './grammar_json.js';
+import {add_grammar_bash} from './grammar_bash.js';
 import {add_grammar_markdown} from './grammar_markdown.js';
 
 /**
@@ -27,4 +28,5 @@ add_grammar_js(syntax_styler_global);
 add_grammar_ts(syntax_styler_global);
 add_grammar_svelte(syntax_styler_global);
 add_grammar_json(syntax_styler_global);
+add_grammar_bash(syntax_styler_global); // before markdown — markdown references bash for fenced code blocks
 add_grammar_markdown(syntax_styler_global);

package/src/lib/syntax_token.ts

@@ -2,14 +2,14 @@ export class SyntaxToken {
 	/**
 	 * The type of the token.
 	 *
-	 * This is usually the key of a pattern in a `Grammar`.
+	 * This is usually the key of a pattern in a `SyntaxGrammar`.
 	 */
 	type: string;
 
 	/**
 	 * The strings or tokens contained by this token.
 	 *
-	 * This will be a token stream if the pattern matched also defined an `inside` grammar.
+	 * This will be a `SyntaxTokenStream` if the pattern matched also defined an `inside` grammar.
 	 */
 	content: string | SyntaxTokenStream;
 
@@ -38,8 +38,8 @@ export class SyntaxToken {
 /**
  * A token stream is an array of strings and `SyntaxToken` objects.
  *
- * Syntax token streams have to fulfill a few properties that are assumed by most functions (mostly internal ones) that process
- * them.
+ * `SyntaxTokenStream` values have to fulfill a few properties that are assumed by most functions
+ * (mostly internal ones) that process them.
  *
  * 1. No adjacent strings.
  * 2. No empty strings.

package/src/lib/tokenize_syntax.ts

@@ -10,11 +10,9 @@ import {SyntaxToken, type SyntaxTokenStream} from './syntax_token.js';
  * This method could be useful in other contexts as well, as a very crude parser.
  *
  * @param text - a string with the code to be styled
- * @param grammar - an object containing the tokens to use
- *
+ * @param grammar - a `SyntaxGrammar` object containing the tokens to use.
  * Usually a language definition like `syntax_styler.get_lang('markup')`.
- *
- * @returns an array of strings and tokens, a token stream
+ * @returns a `SyntaxTokenStream` array of strings and tokens
  *
  * @example
  * ```ts