@particle-academy/fancy-code 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -43,6 +43,13 @@ interface UseEditorEngineReturn {
     handleInput: () => void;
     handleScroll: () => void;
     handleSelect: () => void;
+    /**
+     * Place the caret on a 1-based `line` / `column` and scroll the editor so the
+     * line is centered in view. Out-of-range positions clamp to document bounds.
+     */
+    revealLine: (line: number, column?: number, opts?: {
+        focus?: boolean;
+    }) => void;
     scrollTop: number;
     scrollLeft: number;
 }
@@ -76,6 +83,16 @@ interface CodeEditorProps {
     minHeight?: number;
     /** Maximum height in px (scrolls beyond this) */
     maxHeight?: number;
+    /**
+     * 1-based line to reveal (scroll to + place the caret on). Applied on mount
+     * and whenever it (or `cursorColumn`) changes — so opening a file *at* a line,
+     * or re-targeting an already-open file, scrolls the line into view. Does not
+     * steal focus; call the imperative `revealLine`/`setCursor` (or `focus`) for
+     * that. Out-of-range values clamp to document bounds.
+     */
+    cursorLine?: number;
+    /** 1-based column for {@link cursorLine} (default 1). */
+    cursorColumn?: number;
 }
 interface CodeEditorContextValue {
     /** Get the current document text */
@@ -88,6 +105,16 @@ interface CodeEditorContextValue {
     replaceSelection: (text: string) => void;
     /** Focus the editor */
     focus: () => void;
+    /**
+     * Scroll to + place the caret on a 1-based `line` (optional 1-based `column`),
+     * focusing the editor. Out-of-range positions clamp to document bounds.
+     */
+    revealLine: (line: number, column?: number) => void;
+    /** Place the caret at a 1-based `{ line, column }` and reveal it (focuses). */
+    setCursor: (pos: {
+        line: number;
+        column?: number;
+    }) => void;
     /** Current language name */
     language: string;
     /** Change the active language */
@@ -163,7 +190,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, }: 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, }: CodeEditorProps): react.JSX.Element;
 declare namespace CodeEditorRoot {
     var displayName: string;
 }

package/dist/index.d.ts

@@ -43,6 +43,13 @@ interface UseEditorEngineReturn {
     handleInput: () => void;
     handleScroll: () => void;
     handleSelect: () => void;
+    /**
+     * Place the caret on a 1-based `line` / `column` and scroll the editor so the
+     * line is centered in view. Out-of-range positions clamp to document bounds.
+     */
+    revealLine: (line: number, column?: number, opts?: {
+        focus?: boolean;
+    }) => void;
     scrollTop: number;
     scrollLeft: number;
 }
@@ -76,6 +83,16 @@ interface CodeEditorProps {
     minHeight?: number;
     /** Maximum height in px (scrolls beyond this) */
     maxHeight?: number;
+    /**
+     * 1-based line to reveal (scroll to + place the caret on). Applied on mount
+     * and whenever it (or `cursorColumn`) changes — so opening a file *at* a line,
+     * or re-targeting an already-open file, scrolls the line into view. Does not
+     * steal focus; call the imperative `revealLine`/`setCursor` (or `focus`) for
+     * that. Out-of-range values clamp to document bounds.
+     */
+    cursorLine?: number;
+    /** 1-based column for {@link cursorLine} (default 1). */
+    cursorColumn?: number;
 }
 interface CodeEditorContextValue {
     /** Get the current document text */
@@ -88,6 +105,16 @@ interface CodeEditorContextValue {
     replaceSelection: (text: string) => void;
     /** Focus the editor */
     focus: () => void;
+    /**
+     * Scroll to + place the caret on a 1-based `line` (optional 1-based `column`),
+     * focusing the editor. Out-of-range positions clamp to document bounds.
+     */
+    revealLine: (line: number, column?: number) => void;
+    /** Place the caret at a 1-based `{ line, column }` and reveal it (focuses). */
+    setCursor: (pos: {
+        line: number;
+        column?: number;
+    }) => void;
     /** Current language name */
     language: string;
     /** Change the active language */
@@ -163,7 +190,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, }: 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, }: CodeEditorProps): react.JSX.Element;
 declare namespace CodeEditorRoot {
     var displayName: string;
 }

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createContext, useState, useCallback, useRef, useMemo, useSyncExternalStore, useEffect, useContext } from 'react';
+import { createContext, useState, useCallback, useRef, useEffect, useMemo, useSyncExternalStore, useContext } from 'react';
 import { cn, useControllableState, resolveMediaType, MediaViewer, textareaAdapter, InputTag } from '@particle-academy/react-fancy';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
@@ -1344,6 +1344,19 @@ function highlightCode(source, tokens, colors) {
   return parts.join("");
 }
 
+// src/engine/position.ts
+function lineColumnToOffset(text, line, column = 1) {
+  const lines = text.split("\n");
+  const targetLine = Math.max(1, Math.min(Math.trunc(line) || 1, lines.length));
+  let offset = 0;
+  for (let i = 0; i < targetLine - 1; i++) {
+    offset += lines[i].length + 1;
+  }
+  const lineText = lines[targetLine - 1] ?? "";
+  const col = Math.max(1, Math.min(Math.trunc(column) || 1, lineText.length + 1));
+  return offset + (col - 1);
+}
+
 // src/hooks/use-editor-engine.ts
 var DEFAULT_COLORS = {
   background: "#18181b",
@@ -1458,6 +1471,28 @@ function useEditorEngine({
     setScrollTop(ta.scrollTop);
     setScrollLeft(ta.scrollLeft);
   }, []);
+  const revealLine = useCallback(
+    (line, column = 1, opts) => {
+      const ta = textareaRef.current;
+      if (!ta) return;
+      const offset = lineColumnToOffset(ta.value, line, column);
+      if (opts?.focus) ta.focus();
+      ta.selectionStart = ta.selectionEnd = offset;
+      updateCursorInfo();
+      const panel = ta.closest("[data-fancy-code-panel]");
+      if (!panel) return;
+      const cs = getComputedStyle(ta);
+      const lineHeight = parseFloat(cs.lineHeight) || 19.5;
+      const paddingTop = parseFloat(cs.paddingTop) || 0;
+      const lineIndex = (ta.value.slice(0, offset).match(/\n/g) || []).length;
+      const textareaTopInPanel = ta.getBoundingClientRect().top - panel.getBoundingClientRect().top + panel.scrollTop;
+      const lineTop = textareaTopInPanel + paddingTop + lineIndex * lineHeight;
+      const target = lineTop - panel.clientHeight / 2 + lineHeight / 2;
+      const maxScroll = panel.scrollHeight - panel.clientHeight;
+      panel.scrollTop = Math.max(0, Math.min(target, maxScroll));
+    },
+    [updateCursorInfo]
+  );
   const handleKeyDown = useCallback(
     (e) => {
       if (readOnly) {
@@ -1544,6 +1579,7 @@ function useEditorEngine({
     handleInput,
     handleScroll,
     handleSelect,
+    revealLine,
     scrollTop,
     scrollLeft
   };
@@ -1577,7 +1613,9 @@ function CodeEditorRoot({
   tabSize: tabSizeProp = 2,
   placeholder,
   minHeight,
-  maxHeight
+  maxHeight,
+  cursorLine,
+  cursorColumn
 }) {
   const [currentValue, setCurrentValue] = useControllableState(valueProp, defaultValue, onChange);
   const isDark = useDarkMode();
@@ -1613,6 +1651,11 @@ function CodeEditorRoot({
       setSelectionLength(sel);
     }
   });
+  const { revealLine: revealLineImpl } = engineReturn;
+  useEffect(() => {
+    if (cursorLine == null) return;
+    revealLineImpl(cursorLine, cursorColumn ?? 1, { focus: false });
+  }, [cursorLine, cursorColumn, revealLineImpl]);
   const contextValue = useMemo(
     () => ({
       getValue: () => engineReturn.textareaRef.current?.value ?? currentValue,
@@ -1634,6 +1677,8 @@ function CodeEditorRoot({
         setCurrentValue(ta.value);
       },
       focus: () => engineReturn.textareaRef.current?.focus(),
+      revealLine: (line, column) => engineReturn.revealLine(line, column ?? 1, { focus: true }),
+      setCursor: ({ line, column }) => engineReturn.revealLine(line, column ?? 1, { focus: true }),
       language: currentLanguage,
       setLanguage,
       theme: resolvedTheme,