@particle-academy/fancy-code 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 import * as react from 'react';
 import { RefObject, ReactNode, CSSProperties } from 'react';
+import { DiffAnnotations, LineChangeType } from '@particle-academy/fancy-file-commons';
+export { languageFromFilename } from '@particle-academy/fancy-file-commons';
 import { MediaKind, MediaViewerProps, InputTagProps, InputTagTriggers, InputTagAdapter } from '@particle-academy/react-fancy';
 
 interface ThemeColors {
@@ -11,6 +13,9 @@ interface ThemeColors {
     activeLineBackground: string;
     selectionBackground: string;
     cursorColor: string;
+    diffAdded?: string;
+    diffModified?: string;
+    diffRemoved?: string;
     keyword: string;
     string: string;
     comment: string;
@@ -93,6 +98,15 @@ interface CodeEditorProps {
     cursorLine?: number;
     /** 1-based column for {@link cursorLine} (default 1). */
     cursorColumn?: 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 —
+     * VS Code convention: a green bar for added lines, a blue bar for modified
+     * lines, and a red wedge where lines were deleted. Recomputed live as the
+     * user types (line-level only — cheap). `null`/omitted disables the gutter
+     * marks. Requires `lineNumbers`.
+     */
+    diffBase?: string | null;
 }
 interface CodeEditorContextValue {
     /** Get the current document text */
@@ -151,6 +165,18 @@ interface CodeEditorContextValue {
     textareaRef: RefObject<HTMLTextAreaElement | null>;
     /** Placeholder text */
     placeholder?: string;
+    /**
+     * Totals of the live diff against {@link CodeEditorProps.diffBase} —
+     * `{ added, modified, removed }` — or `null` when no baseline is set.
+     * Handy for a status-bar chip or a host's save indicator.
+     */
+    diffStats: {
+        added: number;
+        modified: number;
+        removed: number;
+    } | null;
+    /** @internal — per-line gutter annotations for the diff marks. */
+    _diffAnnotations: DiffAnnotations | null;
     /** @internal */
     _engineReturn: UseEditorEngineReturn | null;
     /** @internal */
@@ -190,7 +216,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, }: 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, }: CodeEditorProps): react.JSX.Element;
 declare namespace CodeEditorRoot {
     var displayName: string;
 }
@@ -270,11 +296,7 @@ interface ResolveFileKindInput {
     /** MIME type — preferred over the filename when known. */
     mime?: string;
 }
-/**
- * Resolve the fancy-code editor language for a filename. Returns `"plaintext"`
- * (no syntax highlighting) for unknown or extension-less files.
- */
-declare function languageFromFilename(filename?: string): string;
+
 /**
  * Decide whether a file is previewable media (image / video / audio / PDF) or
  * text, from its MIME type (preferred) and/or filename. Media wins when the
@@ -352,6 +374,29 @@ declare namespace FileViewer {
     var displayName: string;
 }
 
+/**
+ * Diff-gutter model — the pure mapping between fancy-file-commons line
+ * annotations and what the CodeEditor gutter renders per line-number row.
+ * Kept DOM-free (like engine/position.ts) so it's unit-testable; the panel
+ * only paints what this resolves.
+ */
+
+/** What one line-number row shows: its own change bar and/or a deletion wedge above. */
+interface GutterDiffMark {
+    /** The line's own change (colored bar), if any. */
+    type?: LineChangeType;
+    /** True when one or more lines were deleted immediately above this line (wedge). */
+    deletedAbove: boolean;
+}
+/** Resolve the mark for a 1-based line, or null when the line is untouched. */
+declare function gutterDiffMark(annotations: DiffAnnotations | null, line: number): GutterDiffMark | null;
+/** Whether the deleted-at-EOF wedge should render under the last line. */
+declare function hasDeletedAtEnd(annotations: DiffAnnotations | null): boolean;
+/** The bar color for a change type, honoring theme overrides. */
+declare function diffMarkColor(type: LineChangeType, colors: ThemeColors): string;
+/** The deletion-wedge color, honoring theme overrides. */
+declare function diffRemovedColor(colors: ThemeColors): string;
+
 /**
  * Tiny, dependency-free Markdown → HTML renderer for the MarkdownEditor preview
  * pane. Covers the common subset — headings, bold/italic, inline + fenced code,
@@ -436,4 +481,4 @@ interface CodeEditorInputTagProps extends Omit<InputTagProps, "adapter"> {
  */
 declare function CodeEditorInputTag(props: CodeEditorInputTagProps): react.JSX.Element;
 
-export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type FileKind, FileViewer, type FileViewerProps, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type ResolveFileKindInput, type ThemeColors, type ThemeDefinition, type Token, type TokenType, type Tokenizer, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, languageFromFilename, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
+export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type ResolveFileKindInput, type ThemeColors, type ThemeDefinition, type Token, type TokenType, type Tokenizer, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import * as react from 'react';
 import { RefObject, ReactNode, CSSProperties } from 'react';
+import { DiffAnnotations, LineChangeType } from '@particle-academy/fancy-file-commons';
+export { languageFromFilename } from '@particle-academy/fancy-file-commons';
 import { MediaKind, MediaViewerProps, InputTagProps, InputTagTriggers, InputTagAdapter } from '@particle-academy/react-fancy';
 
 interface ThemeColors {
@@ -11,6 +13,9 @@ interface ThemeColors {
     activeLineBackground: string;
     selectionBackground: string;
     cursorColor: string;
+    diffAdded?: string;
+    diffModified?: string;
+    diffRemoved?: string;
     keyword: string;
     string: string;
     comment: string;
@@ -93,6 +98,15 @@ interface CodeEditorProps {
     cursorLine?: number;
     /** 1-based column for {@link cursorLine} (default 1). */
     cursorColumn?: 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 —
+     * VS Code convention: a green bar for added lines, a blue bar for modified
+     * lines, and a red wedge where lines were deleted. Recomputed live as the
+     * user types (line-level only — cheap). `null`/omitted disables the gutter
+     * marks. Requires `lineNumbers`.
+     */
+    diffBase?: string | null;
 }
 interface CodeEditorContextValue {
     /** Get the current document text */
@@ -151,6 +165,18 @@ interface CodeEditorContextValue {
     textareaRef: RefObject<HTMLTextAreaElement | null>;
     /** Placeholder text */
     placeholder?: string;
+    /**
+     * Totals of the live diff against {@link CodeEditorProps.diffBase} —
+     * `{ added, modified, removed }` — or `null` when no baseline is set.
+     * Handy for a status-bar chip or a host's save indicator.
+     */
+    diffStats: {
+        added: number;
+        modified: number;
+        removed: number;
+    } | null;
+    /** @internal — per-line gutter annotations for the diff marks. */
+    _diffAnnotations: DiffAnnotations | null;
     /** @internal */
     _engineReturn: UseEditorEngineReturn | null;
     /** @internal */
@@ -190,7 +216,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, }: 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, }: CodeEditorProps): react.JSX.Element;
 declare namespace CodeEditorRoot {
     var displayName: string;
 }
@@ -270,11 +296,7 @@ interface ResolveFileKindInput {
     /** MIME type — preferred over the filename when known. */
     mime?: string;
 }
-/**
- * Resolve the fancy-code editor language for a filename. Returns `"plaintext"`
- * (no syntax highlighting) for unknown or extension-less files.
- */
-declare function languageFromFilename(filename?: string): string;
+
 /**
  * Decide whether a file is previewable media (image / video / audio / PDF) or
  * text, from its MIME type (preferred) and/or filename. Media wins when the
@@ -352,6 +374,29 @@ declare namespace FileViewer {
     var displayName: string;
 }
 
+/**
+ * Diff-gutter model — the pure mapping between fancy-file-commons line
+ * annotations and what the CodeEditor gutter renders per line-number row.
+ * Kept DOM-free (like engine/position.ts) so it's unit-testable; the panel
+ * only paints what this resolves.
+ */
+
+/** What one line-number row shows: its own change bar and/or a deletion wedge above. */
+interface GutterDiffMark {
+    /** The line's own change (colored bar), if any. */
+    type?: LineChangeType;
+    /** True when one or more lines were deleted immediately above this line (wedge). */
+    deletedAbove: boolean;
+}
+/** Resolve the mark for a 1-based line, or null when the line is untouched. */
+declare function gutterDiffMark(annotations: DiffAnnotations | null, line: number): GutterDiffMark | null;
+/** Whether the deleted-at-EOF wedge should render under the last line. */
+declare function hasDeletedAtEnd(annotations: DiffAnnotations | null): boolean;
+/** The bar color for a change type, honoring theme overrides. */
+declare function diffMarkColor(type: LineChangeType, colors: ThemeColors): string;
+/** The deletion-wedge color, honoring theme overrides. */
+declare function diffRemovedColor(colors: ThemeColors): string;
+
 /**
  * Tiny, dependency-free Markdown → HTML renderer for the MarkdownEditor preview
  * pane. Covers the common subset — headings, bold/italic, inline + fenced code,
@@ -436,4 +481,4 @@ interface CodeEditorInputTagProps extends Omit<InputTagProps, "adapter"> {
  */
 declare function CodeEditorInputTag(props: CodeEditorInputTagProps): react.JSX.Element;
 
-export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type FileKind, FileViewer, type FileViewerProps, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type ResolveFileKindInput, type ThemeColors, type ThemeDefinition, type Token, type TokenType, type Tokenizer, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, languageFromFilename, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
+export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type ResolveFileKindInput, type ThemeColors, type ThemeDefinition, type Token, type TokenType, type Tokenizer, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };

package/dist/index.js

@@ -1,5 +1,7 @@
-import { createContext, useState, useCallback, useRef, useEffect, useMemo, useSyncExternalStore, useContext } from 'react';
+import { createContext, useMemo, useState, useCallback, useRef, useEffect, useSyncExternalStore, useContext } from 'react';
 import { cn, useControllableState, resolveMediaType, MediaViewer, textareaAdapter, InputTag } from '@particle-academy/react-fancy';
+import { annotateLines, languageFromFilename } from '@particle-academy/fancy-file-commons';
+export { languageFromFilename } from '@particle-academy/fancy-file-commons';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/components/CodeEditor/CodeEditor.tsx
@@ -11,6 +13,24 @@ function useCodeEditor() {
   }
   return ctx;
 }
+
+// src/components/CodeEditor/diff-gutter.ts
+function gutterDiffMark(annotations, line) {
+  if (!annotations) return null;
+  const a = annotations.byLine[line];
+  if (!a) return null;
+  return { type: a.type, deletedAbove: (a.deletedAbove ?? 0) > 0 };
+}
+function hasDeletedAtEnd(annotations) {
+  return (annotations?.deletedAtEnd ?? 0) > 0;
+}
+var FALLBACK = { added: "#3fb950", modified: "#4184e4", removed: "#f85149" };
+function diffMarkColor(type, colors) {
+  return type === "added" ? colors.diffAdded ?? FALLBACK.added : colors.diffModified ?? FALLBACK.modified;
+}
+function diffRemovedColor(colors) {
+  return colors.diffRemoved ?? FALLBACK.removed;
+}
 function CodeEditorPanel({ className }) {
   const {
     _engineReturn: engine,
@@ -18,6 +38,7 @@ function CodeEditorPanel({ className }) {
     wordWrap,
     readOnly,
     placeholder,
+    _diffAnnotations: diffAnnotations,
     _maxHeight,
     _minHeight
   } = useCodeEditor();
@@ -38,25 +59,80 @@ function CodeEditorPanel({ className }) {
   const gutterWidth = lineNumbers ? `${Math.max(String(lineCount).length, 2) * 0.75 + 1.5}em` : "0";
   const lineNumberElements = useMemo(() => {
     if (!lineNumbers) return null;
+    const removed = diffRemovedColor(themeColors);
     const lines = [];
     for (let i = 1; i <= lineCount; i++) {
+      const mark = gutterDiffMark(diffAnnotations, i);
       lines.push(
-        /* @__PURE__ */ jsx(
+        /* @__PURE__ */ jsxs(
           "div",
           {
+            "data-diff": mark?.type,
+            "data-diff-deleted-above": mark?.deletedAbove ? "" : void 0,
             style: {
+              position: "relative",
               color: i === activeLine ? themeColors.foreground : themeColors.gutterForeground,
               backgroundColor: i === activeLine ? themeColors.activeLineBackground : void 0
             },
             className: "pr-3 text-right text-[13px] leading-[1.5] select-none",
-            children: i
+            children: [
+              mark?.type && /* @__PURE__ */ jsx(
+                "span",
+                {
+                  "aria-hidden": "true",
+                  style: {
+                    position: "absolute",
+                    left: 0,
+                    top: 0,
+                    bottom: 0,
+                    width: 3,
+                    borderRadius: 2,
+                    backgroundColor: diffMarkColor(mark.type, themeColors)
+                  }
+                }
+              ),
+              mark?.deletedAbove && /* @__PURE__ */ jsx(
+                "span",
+                {
+                  "aria-hidden": "true",
+                  style: {
+                    position: "absolute",
+                    left: 0,
+                    top: -4,
+                    width: 0,
+                    height: 0,
+                    borderLeft: `8px solid ${removed}`,
+                    borderTop: "4px solid transparent",
+                    borderBottom: "4px solid transparent"
+                  }
+                }
+              ),
+              i,
+              i === lineCount && hasDeletedAtEnd(diffAnnotations) && /* @__PURE__ */ jsx(
+                "span",
+                {
+                  "aria-hidden": "true",
+                  "data-diff-deleted-at-end": "",
+                  style: {
+                    position: "absolute",
+                    left: 0,
+                    bottom: -4,
+                    width: 0,
+                    height: 0,
+                    borderLeft: `8px solid ${removed}`,
+                    borderTop: "4px solid transparent",
+                    borderBottom: "4px solid transparent"
+                  }
+                }
+              )
+            ]
           },
           i
         )
       );
     }
     return lines;
-  }, [lineNumbers, lineCount, activeLine, themeColors]);
+  }, [lineNumbers, lineCount, activeLine, themeColors, diffAnnotations]);
   const containerStyle = {
     backgroundColor: themeColors.background,
     color: themeColors.foreground,
@@ -1258,6 +1334,9 @@ registerTheme({
     activeLineBackground: "#f8fafc",
     selectionBackground: "#dbeafe",
     cursorColor: "#3b82f6",
+    diffAdded: "#1a7f37",
+    diffModified: "#0969da",
+    diffRemoved: "#cf222e",
     keyword: "#8b5cf6",
     string: "#059669",
     comment: "#94a3b8",
@@ -1286,6 +1365,9 @@ registerTheme({
     activeLineBackground: "#27272a",
     selectionBackground: "#1e3a5f",
     cursorColor: "#60a5fa",
+    diffAdded: "#3fb950",
+    diffModified: "#4184e4",
+    diffRemoved: "#f85149",
     keyword: "#c084fc",
     string: "#34d399",
     comment: "#71717a",
@@ -1615,9 +1697,14 @@ function CodeEditorRoot({
   minHeight,
   maxHeight,
   cursorLine,
-  cursorColumn
+  cursorColumn,
+  diffBase
 }) {
   const [currentValue, setCurrentValue] = useControllableState(valueProp, defaultValue, onChange);
+  const diffAnnotations = useMemo(
+    () => diffBase == null ? null : annotateLines(diffBase, currentValue),
+    [diffBase, currentValue]
+  );
   const isDark = useDarkMode();
   const resolvedTheme = theme === "auto" ? isDark ? "dark" : "light" : theme;
   const [currentLanguage, setCurrentLanguageState] = useState(() => {
@@ -1696,11 +1783,17 @@ function CodeEditorRoot({
       selectionLength,
       textareaRef: engineReturn.textareaRef,
       placeholder,
+      diffStats: diffAnnotations ? {
+        added: diffAnnotations.added,
+        modified: diffAnnotations.modified,
+        removed: diffAnnotations.removed
+      } : null,
+      _diffAnnotations: diffAnnotations,
       _engineReturn: engineReturn,
       _minHeight: minHeight,
       _maxHeight: maxHeight
     }),
-    [engineReturn, currentValue, currentLanguage, setLanguage, resolvedTheme, readOnly, showLineNumbers, isWordWrap, tabSizeProp, cursorPosition, selectionLength, setCurrentValue, placeholder, minHeight, maxHeight]
+    [engineReturn, currentValue, currentLanguage, setLanguage, resolvedTheme, readOnly, showLineNumbers, isWordWrap, tabSizeProp, cursorPosition, selectionLength, setCurrentValue, placeholder, diffAnnotations, minHeight, maxHeight]
   );
   return /* @__PURE__ */ jsx(CodeEditorContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsx(
     "div",
@@ -1876,44 +1969,6 @@ function MarkdownEditor({
   );
 }
 MarkdownEditor.displayName = "MarkdownEditor";
-var EXT_LANGUAGE = {
-  js: "javascript",
-  mjs: "javascript",
-  cjs: "javascript",
-  jsx: "javascript",
-  json: "javascript",
-  // the JS tokenizer highlights JSON acceptably
-  jsonc: "javascript",
-  ts: "typescript",
-  mts: "typescript",
-  cts: "typescript",
-  tsx: "typescript",
-  html: "html",
-  htm: "html",
-  xml: "html",
-  xhtml: "html",
-  vue: "html",
-  php: "php",
-  phtml: "php",
-  py: "python",
-  pyw: "python",
-  go: "go",
-  md: "markdown",
-  markdown: "markdown",
-  mkd: "markdown",
-  mdx: "markdown"
-};
-function basename(filename) {
-  return filename.split(/[?#]/, 1)[0].split(/[\\/]/).pop() ?? "";
-}
-function languageFromFilename(filename) {
-  if (!filename) return "plaintext";
-  const seg = basename(filename);
-  const dot = seg.lastIndexOf(".");
-  if (dot <= 0) return "plaintext";
-  const ext = seg.slice(dot + 1).toLowerCase();
-  return EXT_LANGUAGE[ext] ?? "plaintext";
-}
 function resolveFileKind({ filename, mime }) {
   const media = resolveMediaType({ mime, src: filename });
   if (media !== "unknown") return { kind: "media", mediaKind: media };
@@ -1997,6 +2052,6 @@ function CodeEditorInputTag(props) {
   return /* @__PURE__ */ jsx(InputTag, { adapter, ...props });
 }
 
-export { CodeEditor, CodeEditorInputTag, FileViewer, MarkdownEditor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, languageFromFilename, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
+export { CodeEditor, CodeEditorInputTag, FileViewer, MarkdownEditor, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map