@particle-academy/fancy-code 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,29 +1,9 @@
 import * as react from 'react';
 import { RefObject, ReactNode, CSSProperties } from 'react';
+import { ThemeColors, DiffAnnotations, LineChangeType, Token, Tokenizer } from '@particle-academy/fancy-file-commons';
+export { ThemeColors, Token, TokenType, Tokenizer, languageFromFilename } from '@particle-academy/fancy-file-commons';
 import { MediaKind, MediaViewerProps, InputTagProps, InputTagTriggers, InputTagAdapter } from '@particle-academy/react-fancy';
 
-interface ThemeColors {
-    background: string;
-    foreground: string;
-    gutterBackground: string;
-    gutterForeground: string;
-    gutterBorder: string;
-    activeLineBackground: string;
-    selectionBackground: string;
-    cursorColor: string;
-    keyword: string;
-    string: string;
-    comment: string;
-    number: string;
-    operator: string;
-    function: string;
-    type: string;
-    tag: string;
-    attribute: string;
-    attributeValue: string;
-    punctuation: string;
-    variable: string;
-}
 interface ThemeDefinition {
     /** Unique theme name */
     name: string;
@@ -93,6 +73,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 +140,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 +191,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 +271,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 +349,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,
@@ -362,14 +382,6 @@ declare namespace FileViewer {
  */
 declare function renderMarkdown(markdown: string): string;
 
-type TokenType = "keyword" | "string" | "comment" | "number" | "operator" | "tag" | "attribute" | "attributeValue" | "punctuation" | "function" | "type" | "variable" | "plain";
-interface Token {
-    type: TokenType;
-    start: number;
-    end: number;
-}
-type Tokenizer = (source: string) => Token[];
-
 /**
  * Minimal, dependency-free Markdown tokenizer for editor highlighting. Line-based
  * for block constructs (fences, headings, blockquotes, list markers) plus a few
@@ -436,4 +448,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 ThemeDefinition, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };

package/dist/index.d.ts

@@ -1,29 +1,9 @@
 import * as react from 'react';
 import { RefObject, ReactNode, CSSProperties } from 'react';
+import { ThemeColors, DiffAnnotations, LineChangeType, Token, Tokenizer } from '@particle-academy/fancy-file-commons';
+export { ThemeColors, Token, TokenType, Tokenizer, languageFromFilename } from '@particle-academy/fancy-file-commons';
 import { MediaKind, MediaViewerProps, InputTagProps, InputTagTriggers, InputTagAdapter } from '@particle-academy/react-fancy';
 
-interface ThemeColors {
-    background: string;
-    foreground: string;
-    gutterBackground: string;
-    gutterForeground: string;
-    gutterBorder: string;
-    activeLineBackground: string;
-    selectionBackground: string;
-    cursorColor: string;
-    keyword: string;
-    string: string;
-    comment: string;
-    number: string;
-    operator: string;
-    function: string;
-    type: string;
-    tag: string;
-    attribute: string;
-    attributeValue: string;
-    punctuation: string;
-    variable: string;
-}
 interface ThemeDefinition {
     /** Unique theme name */
     name: string;
@@ -93,6 +73,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 +140,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 +191,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 +271,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 +349,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,
@@ -362,14 +382,6 @@ declare namespace FileViewer {
  */
 declare function renderMarkdown(markdown: string): string;
 
-type TokenType = "keyword" | "string" | "comment" | "number" | "operator" | "tag" | "attribute" | "attributeValue" | "punctuation" | "function" | "type" | "variable" | "plain";
-interface Token {
-    type: TokenType;
-    start: number;
-    end: number;
-}
-type Tokenizer = (source: string) => Token[];
-
 /**
  * Minimal, dependency-free Markdown tokenizer for editor highlighting. Line-based
  * for block constructs (fences, headings, blockquotes, list markers) plus a few
@@ -436,4 +448,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 ThemeDefinition, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };