@particle-academy/fancy-code 0.11.0 → 0.12.1

package/dist/index.d.cts

@@ -73,6 +73,12 @@ interface CodeEditorProps {
     cursorLine?: number;
     /** 1-based column for {@link cursorLine} (default 1). */
     cursorColumn?: number;
+    /**
+     * 1-based lines to mark with a full-width band — "here is the line you were
+     * sent to". Purely visual and independent of the caret; lines outside the
+     * document are ignored. Sized for unwrapped lines, as the gutter is.
+     */
+    highlightLines?: readonly number[];
     /**
      * Baseline document for the diff gutter. When set, the line-number column
      * shows per-line change marks of the CURRENT value against this baseline —
@@ -158,6 +164,8 @@ interface CodeEditorContextValue {
     _minHeight?: number;
     /** @internal */
     _maxHeight?: number;
+    /** @internal — lines to band; see {@link CodeEditorProps.highlightLines}. */
+    _highlightLines?: readonly number[];
 }
 interface CodeEditorToolbarProps {
     children?: ReactNode;
@@ -191,7 +199,7 @@ declare namespace CodeEditorStatusBar {
     var displayName: string;
 }
 
-declare function CodeEditorRoot({ children, className, value: valueProp, defaultValue, onChange, language: languageProp, onLanguageChange, theme, readOnly, lineNumbers: lineNumbersProp, wordWrap: wordWrapProp, tabSize: tabSizeProp, placeholder, minHeight, maxHeight, cursorLine, cursorColumn, diffBase, }: CodeEditorProps): react.JSX.Element;
+declare function CodeEditorRoot({ children, className, value: valueProp, defaultValue, onChange, language: languageProp, onLanguageChange, theme, readOnly, lineNumbers: lineNumbersProp, wordWrap: wordWrapProp, tabSize: tabSizeProp, placeholder, minHeight, maxHeight, cursorLine, cursorColumn, diffBase, highlightLines, }: CodeEditorProps): react.JSX.Element;
 declare namespace CodeEditorRoot {
     var displayName: string;
 }
@@ -328,6 +336,19 @@ interface FileViewerProps {
     lineNumbers?: boolean;
     /** Wrap long lines in the text editor (default `false`). */
     wordWrap?: boolean;
+    /**
+     * 1-based line to land on: scrolled to the middle of the view, caret placed,
+     * and highlighted. Applied on mount and again whenever it changes, so
+     * re-targeting an open file scrolls again. Text files only; does not steal focus.
+     */
+    line?: number;
+    /** 1-based column for {@link line} (default 1). */
+    column?: number;
+    /**
+     * Lines to highlight. Defaults to `[line]` when `line` is set; pass your own
+     * (a range, several hits) to override, or `[]` to land without highlighting.
+     */
+    highlightLines?: readonly number[];
     /** Editor height bounds (px). */
     minHeight?: number;
     maxHeight?: number;
@@ -353,7 +374,7 @@ interface FileViewerProps {
  * <FileViewer filename="logo.png" src={url} style={{ height: 360 }} />
  * ```
  */
-declare function FileViewer({ filename, mime, src, value, onChange, readOnly, theme, fileKind, lineNumbers, wordWrap, minHeight, maxHeight, mediaProps, className, style, }: FileViewerProps): react.JSX.Element;
+declare function FileViewer({ filename, mime, src, value, onChange, readOnly, theme, fileKind, lineNumbers, wordWrap, line, column, highlightLines, minHeight, maxHeight, mediaProps, className, style, }: FileViewerProps): react.JSX.Element;
 declare namespace FileViewer {
     var displayName: string;
 }

package/dist/index.d.ts

@@ -73,6 +73,12 @@ interface CodeEditorProps {
     cursorLine?: number;
     /** 1-based column for {@link cursorLine} (default 1). */
     cursorColumn?: number;
+    /**
+     * 1-based lines to mark with a full-width band — "here is the line you were
+     * sent to". Purely visual and independent of the caret; lines outside the
+     * document are ignored. Sized for unwrapped lines, as the gutter is.
+     */
+    highlightLines?: readonly number[];
     /**
      * Baseline document for the diff gutter. When set, the line-number column
      * shows per-line change marks of the CURRENT value against this baseline —
@@ -158,6 +164,8 @@ interface CodeEditorContextValue {
     _minHeight?: number;
     /** @internal */
     _maxHeight?: number;
+    /** @internal — lines to band; see {@link CodeEditorProps.highlightLines}. */
+    _highlightLines?: readonly number[];
 }
 interface CodeEditorToolbarProps {
     children?: ReactNode;
@@ -191,7 +199,7 @@ declare namespace CodeEditorStatusBar {
     var displayName: string;
 }
 
-declare function CodeEditorRoot({ children, className, value: valueProp, defaultValue, onChange, language: languageProp, onLanguageChange, theme, readOnly, lineNumbers: lineNumbersProp, wordWrap: wordWrapProp, tabSize: tabSizeProp, placeholder, minHeight, maxHeight, cursorLine, cursorColumn, diffBase, }: CodeEditorProps): react.JSX.Element;
+declare function CodeEditorRoot({ children, className, value: valueProp, defaultValue, onChange, language: languageProp, onLanguageChange, theme, readOnly, lineNumbers: lineNumbersProp, wordWrap: wordWrapProp, tabSize: tabSizeProp, placeholder, minHeight, maxHeight, cursorLine, cursorColumn, diffBase, highlightLines, }: CodeEditorProps): react.JSX.Element;
 declare namespace CodeEditorRoot {
     var displayName: string;
 }
@@ -328,6 +336,19 @@ interface FileViewerProps {
     lineNumbers?: boolean;
     /** Wrap long lines in the text editor (default `false`). */
     wordWrap?: boolean;
+    /**
+     * 1-based line to land on: scrolled to the middle of the view, caret placed,
+     * and highlighted. Applied on mount and again whenever it changes, so
+     * re-targeting an open file scrolls again. Text files only; does not steal focus.
+     */
+    line?: number;
+    /** 1-based column for {@link line} (default 1). */
+    column?: number;
+    /**
+     * Lines to highlight. Defaults to `[line]` when `line` is set; pass your own
+     * (a range, several hits) to override, or `[]` to land without highlighting.
+     */
+    highlightLines?: readonly number[];
     /** Editor height bounds (px). */
     minHeight?: number;
     maxHeight?: number;
@@ -353,7 +374,7 @@ interface FileViewerProps {
  * <FileViewer filename="logo.png" src={url} style={{ height: 360 }} />
  * ```
  */
-declare function FileViewer({ filename, mime, src, value, onChange, readOnly, theme, fileKind, lineNumbers, wordWrap, minHeight, maxHeight, mediaProps, className, style, }: FileViewerProps): react.JSX.Element;
+declare function FileViewer({ filename, mime, src, value, onChange, readOnly, theme, fileKind, lineNumbers, wordWrap, line, column, highlightLines, minHeight, maxHeight, mediaProps, className, style, }: FileViewerProps): react.JSX.Element;
 declare namespace FileViewer {
     var displayName: string;
 }

package/dist/index.js

@@ -40,12 +40,14 @@ function CodeEditorPanel({ className }) {
     placeholder,
     _diffAnnotations: diffAnnotations,
     _maxHeight,
-    _minHeight
+    _minHeight,
+    _highlightLines: highlightLines
   } = useCodeEditor();
   const lineNumberElements = useMemo(() => {
     if (!engine || !lineNumbers) return null;
     const { themeColors: themeColors2, lineCount: lineCount2, activeLine: activeLine2 } = engine;
     const removed = diffRemovedColor(themeColors2);
+    const highlighted = new Set(highlightLines ?? []);
     const lines = [];
     for (let i = 1; i <= lineCount2; i++) {
       const mark = gutterDiffMark(diffAnnotations, i);
@@ -57,8 +59,9 @@ function CodeEditorPanel({ className }) {
             "data-diff-deleted-above": mark?.deletedAbove ? "" : void 0,
             style: {
               position: "relative",
-              color: i === activeLine2 ? themeColors2.foreground : themeColors2.gutterForeground,
-              backgroundColor: i === activeLine2 ? themeColors2.activeLineBackground : void 0
+              color: i === activeLine2 || highlighted.has(i) ? themeColors2.foreground : themeColors2.gutterForeground,
+              backgroundColor: i === activeLine2 ? themeColors2.activeLineBackground : void 0,
+              fontWeight: highlighted.has(i) ? 600 : void 0
             },
             className: "pr-3 text-right text-[13px] leading-[1.5] select-none",
             children: [
@@ -118,7 +121,7 @@ function CodeEditorPanel({ className }) {
       );
     }
     return lines;
-  }, [engine, lineNumbers, diffAnnotations]);
+  }, [engine, lineNumbers, diffAnnotations, highlightLines]);
   if (!engine) return null;
   const {
     textareaRef,
@@ -161,6 +164,21 @@ function CodeEditorPanel({ className }) {
           }
         ),
         /* @__PURE__ */ jsxs("div", { className: cn("relative flex-1", wordWrap && "min-w-0"), children: [
+          (highlightLines ?? []).filter((n) => Number.isInteger(n) && n >= 1 && n <= lineCount).map((n) => /* @__PURE__ */ jsx(
+            "div",
+            {
+              "data-fancy-code-highlight-line": n,
+              "aria-hidden": "true",
+              className: "pointer-events-none absolute inset-x-0 text-[13px] leading-[1.5]",
+              style: {
+                top: `calc(0.625rem + ${(n - 1) * 1.5}em)`,
+                height: "1.5em",
+                backgroundColor: themeColors.selectionBackground,
+                opacity: 0.55
+              }
+            },
+            `highlight-${n}`
+          )),
           /* @__PURE__ */ jsx(
             "pre",
             {
@@ -1516,7 +1534,8 @@ function CodeEditorRoot({
   maxHeight,
   cursorLine,
   cursorColumn,
-  diffBase
+  diffBase,
+  highlightLines
 }) {
   const [currentValue, setCurrentValue] = useControllableState(valueProp, defaultValue, onChange);
   const diffAnnotations = useMemo(
@@ -1609,9 +1628,10 @@ function CodeEditorRoot({
       _diffAnnotations: diffAnnotations,
       _engineReturn: engineReturn,
       _minHeight: minHeight,
-      _maxHeight: maxHeight
+      _maxHeight: maxHeight,
+      _highlightLines: highlightLines
     }),
-    [engineReturn, currentValue, currentLanguage, setLanguage, resolvedTheme, readOnly, showLineNumbers, isWordWrap, tabSizeProp, cursorPosition, selectionLength, setCurrentValue, placeholder, diffAnnotations, minHeight, maxHeight]
+    [engineReturn, currentValue, currentLanguage, setLanguage, resolvedTheme, readOnly, showLineNumbers, isWordWrap, tabSizeProp, cursorPosition, selectionLength, setCurrentValue, placeholder, diffAnnotations, minHeight, maxHeight, highlightLines]
   );
   return /* @__PURE__ */ jsx(CodeEditorContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsx(
     "div",
@@ -1716,6 +1736,9 @@ function FileViewer({
   fileKind,
   lineNumbers = true,
   wordWrap = false,
+  line,
+  column,
+  highlightLines,
   minHeight,
   maxHeight,
   mediaProps,
@@ -1767,6 +1790,9 @@ function FileViewer({
           wordWrap,
           minHeight,
           maxHeight,
+          cursorLine: line,
+          cursorColumn: column,
+          highlightLines: highlightLines ?? (line != null ? [line] : void 0),
           children: /* @__PURE__ */ jsx(CodeEditor.Panel, {})
         }
       )
@@ -1782,8 +1808,27 @@ function escapeHtml(s) {
 function escapeAttr(s) {
   return s.replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
+var LINK_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "mailto", "tel"]);
+function schemeOf(url) {
+  let s = "";
+  for (const ch of url) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code === 9 || code === 10 || code === 13) continue;
+    if (s === "" && code <= 32) continue;
+    s += ch;
+  }
+  const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(s);
+  return m ? m[1].toLowerCase() : null;
+}
+function safeUrl(url, kind) {
+  const scheme = schemeOf(url);
+  if (scheme === null) return true;
+  if (scheme === "http" || scheme === "https") return true;
+  if (kind === "link") return LINK_SCHEMES.has(scheme);
+  return scheme === "data" && /^data:image\/(png|jpe?g|gif|webp|avif|bmp);/i.test(url.trim());
+}
 function inline(text) {
-  return text.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (_m, alt, src, title) => `<img src="${escapeAttr(src)}" alt="${escapeAttr(alt)}"${title ? ` title="${escapeAttr(title)}"` : ""}>`).replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (_m, t, href, title) => `<a href="${escapeAttr(href)}"${title ? ` title="${escapeAttr(title)}"` : ""} rel="noopener">${t}</a>`).replace(/`([^`]+)`/g, (_m, c) => `<code>${c}</code>`).replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, "<strong>$2</strong>").replace(/(\*|_)(?=\S)([\s\S]*?\S)\1/g, "<em>$2</em>");
+  return text.replace(/!\[([^\]]*)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (_m, alt, src, title) => safeUrl(src, "image") ? `<img src="${escapeAttr(src)}" alt="${escapeAttr(alt)}"${title ? ` title="${escapeAttr(title)}"` : ""}>` : alt).replace(/\[([^\]]+)\]\(([^)\s]+)(?:\s+"([^"]*)")?\)/g, (_m, t, href, title) => safeUrl(href, "link") ? `<a href="${escapeAttr(href)}"${title ? ` title="${escapeAttr(title)}"` : ""} rel="noopener">${t}</a>` : t).replace(/`([^`]+)`/g, (_m, c) => `<code>${c}</code>`).replace(/(\*\*|__)(?=\S)([\s\S]*?\S)\1/g, "<strong>$2</strong>").replace(/(\*|_)(?=\S)([\s\S]*?\S)\1/g, "<em>$2</em>");
 }
 function renderMarkdown(markdown) {
   const lines = markdown.replace(/\r\n?/g, "\n").split("\n");