specra 0.2.59 → 0.2.61

package/dist/components/docs/CodeBlock.svelte

@@ -5,9 +5,24 @@
     code: string;
     language: string;
     filename?: string;
+    showLineNumbers?: boolean;
+    diff?: boolean;
   }
 
-  let { code, language, filename }: Props = $props();
+  let { code, language, filename, showLineNumbers = false, diff = false }: Props = $props();
+
+  // Diff add/remove markers apply either to a `diff` language or to any block
+  // explicitly opted in via the `diff` fence-meta flag.
+  let diffEnabled = $derived(diff || language === 'diff');
+
+  // Languages whose syntax the JS/TS-oriented tokenizer below does NOT model.
+  // Highlighting these would mis-colour prose markup (e.g. a markdown list `-`
+  // becomes a red "operator", `# heading` becomes a grey "comment"), so they are
+  // rendered as plain, uncoloured text instead.
+  const PLAIN_LANGUAGES = new Set([
+    'markdown', 'md', 'mdx', 'text', 'txt', 'plaintext', 'plain', '',
+  ]);
+  let isPlain = $derived(PLAIN_LANGUAGES.has((language || '').toLowerCase()));
 
   let copied = $state(false);
   let copyTimeout: ReturnType<typeof setTimeout> | undefined;
@@ -115,7 +130,7 @@
 
   <!-- Code content -->
   <div class="bg-muted/30 dark:bg-muted/20 rounded-b-xl overflow-x-auto border border-border/50">
-    <pre class="p-2 text-[13px] font-mono leading-relaxed text-gray-800 dark:text-gray-200"><code class="table w-full">{#each lines as line, i}{@const isDeletion = language === 'diff' && line.startsWith('-') && !line.startsWith('--')}{@const isAddition = language === 'diff' && line.startsWith('+') && !line.startsWith('++')}{@const isDiff = isDeletion || isAddition}{@const diffBgClass = isDeletion ? 'bg-red-500/5 dark:bg-red-500/10' : isAddition ? 'bg-green-500/5 dark:bg-green-500/10' : ''}{@const diffMarkerClass = isDeletion ? 'text-red-600 dark:text-red-400' : isAddition ? 'text-green-600 dark:text-green-400' : ''}{@const tokens = tokenizeLine(line)}<div class="table-row {diffBgClass}"><span class="table-cell pr-4 text-right select-none text-muted-foreground/40 w-8 align-top">{i + 1}</span><span class="table-cell align-top">{#if tokens.length === 0}&nbsp;{:else}{#each tokens as token, j}{#if j === 0 && isDiff && token.value.length > 0 && (token.value[0] === '+' || token.value[0] === '-')}<span class="{diffMarkerClass} font-bold">{token.value[0]}</span>{#if token.value.length > 1}<span class="token-{token.type}">{token.value.slice(1)}</span>{/if}{:else}<span class="token-{token.type}">{token.value}</span>{/if}{/each}{/if}</span></div>{/each}</code></pre>
+    <pre class="p-2 text-[13px] font-mono leading-relaxed text-gray-800 dark:text-gray-200"><code class="table w-full">{#each lines as line, i}{@const isDeletion = diffEnabled && line.startsWith('-') && !line.startsWith('--')}{@const isAddition = diffEnabled && line.startsWith('+') && !line.startsWith('++')}{@const isDiff = isDeletion || isAddition}{@const diffBgClass = isDeletion ? 'bg-red-500/5 dark:bg-red-500/10' : isAddition ? 'bg-green-500/5 dark:bg-green-500/10' : ''}{@const diffMarkerClass = isDeletion ? 'text-red-600 dark:text-red-400' : isAddition ? 'text-green-600 dark:text-green-400' : ''}{@const tokens = isPlain ? [] : tokenizeLine(line)}<div class="table-row {diffBgClass}">{#if showLineNumbers}<span class="table-cell pr-4 text-right select-none text-muted-foreground/40 w-8 align-top">{i + 1}</span>{/if}<span class="table-cell align-top">{#if isPlain}{#if isDiff}<span class="{diffMarkerClass} font-bold">{line[0]}</span>{line.slice(1)}{:else}{#if line}{line}{:else}&nbsp;{/if}{/if}{:else}{#if tokens.length === 0}&nbsp;{:else}{#each tokens as token, j}{#if j === 0 && isDiff && token.value.length > 0 && (token.value[0] === '+' || token.value[0] === '-')}<span class="{diffMarkerClass} font-bold">{token.value[0]}</span>{#if token.value.length > 1}<span class="token-{token.type}">{token.value.slice(1)}</span>{/if}{:else}<span class="token-{token.type}">{token.value}</span>{/if}{/each}{/if}{/if}</span></div>{/each}</code></pre>
   </div>
 </div>
 

package/dist/components/docs/CodeBlock.svelte.d.ts

@@ -2,6 +2,8 @@ interface Props {
     code: string;
     language: string;
     filename?: string;
+    showLineNumbers?: boolean;
+    diff?: boolean;
 }
 declare const CodeBlock: import("svelte").Component<Props, {}, "">;
 type CodeBlock = ReturnType<typeof CodeBlock>;

package/dist/mdx.js

@@ -3,6 +3,7 @@ import path from "path";
 import matter from "gray-matter";
 import yaml from "js-yaml";
 import { rehypeBasePath } from "./rehype-base-path.js";
+import { remarkCodeMeta } from "./remark-code-meta.js";
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkGfm from "remark-gfm";
@@ -518,6 +519,7 @@ async function processMarkdownToHtml(markdown) {
         .use(remarkParse)
         .use(remarkGfm)
         .use(remarkMath)
+        .use(remarkCodeMeta)
         .use(remarkRehype, { allowDangerousHtml: true })
         .use(rehypeRaw)
         .use(rehypeSlug)
@@ -575,9 +577,23 @@ function extractCodeBlockProps(node) {
     const language = langClass ? langClass.replace('language-', '') : 'txt';
     // Extract text content from the code element
     const code = extractTextContent(codeChild).replace(/\n$/, '');
-    // Check for filename in data attributes (e.g. from remark-code-meta)
-    const filename = node.properties?.['data-filename'] || codeChild.properties?.['data-filename'];
-    return { code, language, ...(filename ? { filename } : {}) };
+    // Read attributes set by remark-code-meta from the fence meta. rehypeRaw
+    // normalises `data-foo` to the camel-cased `dataFoo` hast property, so accept
+    // both spellings, on either the <pre> or the <code>.
+    const readDataAttr = (camel, kebab) => node.properties?.[camel] ?? node.properties?.[kebab] ??
+        codeChild.properties?.[camel] ?? codeChild.properties?.[kebab];
+    const filename = readDataAttr('dataFilename', 'data-filename');
+    const lineNumbers = readDataAttr('dataLineNumbers', 'data-line-numbers');
+    const showLineNumbers = lineNumbers === 'true' || lineNumbers === true || lineNumbers === '';
+    const diffAttr = readDataAttr('dataDiff', 'data-diff');
+    const diff = diffAttr === 'true' || diffAttr === true || diffAttr === '';
+    return {
+        code,
+        language,
+        ...(filename ? { filename } : {}),
+        ...(showLineNumbers ? { showLineNumbers: true } : {}),
+        ...(diff ? { diff: true } : {}),
+    };
 }
 /**
  * Detect GitHub-style alert blockquotes: > [!WARNING] content
@@ -1176,6 +1192,7 @@ async function processMarkdownToMdxNodes(markdown) {
         .use(remarkParse)
         .use(remarkGfm)
         .use(remarkMath)
+        .use(remarkCodeMeta)
         .use(remarkRehype, { allowDangerousHtml: true })
         .use(rehypeRaw)
         .use(rehypeSlug)

package/dist/remark-code-meta.d.ts

@@ -1,6 +1,16 @@
 /**
- * Remark plugin to extract code block meta strings and pass them as props
- * Converts: ```js filename.js
- * Into props: { language: 'js', meta: 'filename.js' }
+ * Remark plugin to read a code block's fence meta string and expose the
+ * recognised options as `data-*` attributes on the rendered <code>.
+ *
+ * Supported syntax:
+ *   ```js title="app.js"          -> data-filename="app.js"
+ *   ```ts title='src/index.ts'    -> data-filename="src/index.ts"
+ *   ```js showLineNumbers         -> data-line-numbers="true"
+ *   ```js showLineNumbers=true    -> data-line-numbers="true"
+ *   ```html diff                  -> data-diff="true"
+ *
+ * Line numbers and diff markers are opt-in: only an explicit flag turns them on.
+ * `diff` lets a syntax-highlighted block (any language) render leading `-`/`+`
+ * lines as removed/added without auto-detecting them across every language.
  */
 export declare function remarkCodeMeta(): (tree: any) => void;

package/dist/remark-code-meta.js

@@ -1,16 +1,50 @@
 /**
- * Remark plugin to extract code block meta strings and pass them as props
- * Converts: ```js filename.js
- * Into props: { language: 'js', meta: 'filename.js' }
+ * Remark plugin to read a code block's fence meta string and expose the
+ * recognised options as `data-*` attributes on the rendered <code>.
+ *
+ * Supported syntax:
+ *   ```js title="app.js"          -> data-filename="app.js"
+ *   ```ts title='src/index.ts'    -> data-filename="src/index.ts"
+ *   ```js showLineNumbers         -> data-line-numbers="true"
+ *   ```js showLineNumbers=true    -> data-line-numbers="true"
+ *   ```html diff                  -> data-diff="true"
+ *
+ * Line numbers and diff markers are opt-in: only an explicit flag turns them on.
+ * `diff` lets a syntax-highlighted block (any language) render leading `-`/`+`
+ * lines as removed/added without auto-detecting them across every language.
  */
 export function remarkCodeMeta() {
     return (tree) => {
         const visit = (node) => {
             if (node.type === 'code' && node.meta) {
-                // Store the meta string in the node's data
-                node.data = node.data || {};
-                node.data.hProperties = node.data.hProperties || {};
-                node.data.hProperties.meta = node.meta;
+                const meta = node.meta;
+                const hProperties = {};
+                // title="..." / title='...' -> filename shown in the code block header.
+                const titleMatch = meta.match(/\btitle\s*=\s*"([^"]*)"/i) ||
+                    meta.match(/\btitle\s*=\s*'([^']*)'/i);
+                if (titleMatch) {
+                    hProperties['data-filename'] = titleMatch[1];
+                }
+                // Strip quoted `key="..."` / `key='...'` values before scanning for bare
+                // flags, so a value like title="my diff notes" can't false-match below.
+                const flags = meta
+                    .replace(/\b\w+\s*=\s*"[^"]*"/g, ' ')
+                    .replace(/\b\w+\s*=\s*'[^']*'/g, ' ');
+                // showLineNumbers (opt-in). Bare flag or `=true` enables; `=false` keeps off.
+                const lineNumbersMatch = flags.match(/\bshowLineNumbers(?:\s*=\s*(true|false))?\b/i);
+                if (lineNumbersMatch &&
+                    (lineNumbersMatch[1] === undefined ||
+                        lineNumbersMatch[1].toLowerCase() === 'true')) {
+                    hProperties['data-line-numbers'] = 'true';
+                }
+                // diff (opt-in): treat leading -/+ lines as removed/added.
+                if (/\bdiff\b/i.test(flags)) {
+                    hProperties['data-diff'] = 'true';
+                }
+                if (Object.keys(hProperties).length > 0) {
+                    node.data = node.data || {};
+                    node.data.hProperties = { ...(node.data.hProperties || {}), ...hProperties };
+                }
             }
             if (node.children) {
                 node.children.forEach(visit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specra",
-  "version": "0.2.59",
+  "version": "0.2.61",
   "description": "A modern documentation library for SvelteKit with built-in versioning, API reference generation, full-text search, and MDX support",
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",