@particle-academy/fancy-code 0.15.1 → 0.17.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { RefObject, ReactNode, CSSProperties, ComponentType } 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 { ThemeColors, DiffAnnotations, LineChangeType, Tokenizer } from '@particle-academy/fancy-file-commons';
+export { ThemeColors, Token, TokenType, Tokenizer, languageFromFilename, tokenizeMarkdown } from '@particle-academy/fancy-file-commons';
 import { MediaKind, MediaViewerProps, FauxClientProps, InputTagProps, InputTagTriggers, InputTagAdapter } from '@particle-academy/react-fancy';
 
 interface ThemeDefinition {
@@ -21,6 +21,11 @@ interface UseEditorEngineReturn {
     themeColors: ThemeColors;
     handleKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
     handleInput: () => void;
+    /**
+     * Ends the focus session: disarms Tab-indent so the next Tab into the editor
+     * moves focus rather than indenting. Wire to the textarea's `onBlur`.
+     */
+    handleBlur: () => void;
     handleScroll: () => void;
     handleSelect: () => void;
     /**
@@ -49,13 +54,22 @@ interface CodeEditorProps {
     onLanguageChange?: (lang: string) => void;
     /** Theme name: "light", "dark", "auto", or a custom registered name (default: "auto") */
     theme?: string;
-    /** Prevent editing (default: false) */
+    /**
+     * Prevent editing (default: false). Read-only editors still take every
+     * navigation key, and Tab / Shift+Tab move focus out.
+     */
     readOnly?: boolean;
     /** Show line numbers (default: true) */
     lineNumbers?: boolean;
     /** Enable word wrap (default: false) */
     wordWrap?: boolean;
-    /** Tab size in spaces (default: 2) */
+    /**
+     * Tab size in spaces (default: 2).
+     *
+     * Tab / Shift+Tab indent and dedent only once the user has edited in the
+     * current focus session; until then Tab moves focus like any other control,
+     * so keyboard users are never trapped (WCAG 2.1.2). Escape and blur disarm.
+     */
     tabSize?: number;
     /** Placeholder shown when empty */
     placeholder?: string;
@@ -88,7 +102,19 @@ interface CodeEditorProps {
      * marks. Requires `lineNumbers`.
      */
     diffBase?: string | null;
+    /**
+     * Accessible name of the editing surface. Lands on the `<textarea>` a person
+     * types into, not on a wrapper. Default "Code editor"; ignored when
+     * `aria-labelledby` is set.
+     */
+    "aria-label"?: string;
+    /** Id(s) of the element(s) naming the editing surface. Wins over `aria-label`. */
+    "aria-labelledby"?: string;
+    /** Id(s) of the element(s) describing the editing surface. */
+    "aria-describedby"?: string;
 }
+/** The accessible-name props every editor forwards to its textarea. */
+type EditorAriaProps = Pick<CodeEditorProps, "aria-label" | "aria-labelledby" | "aria-describedby">;
 interface CodeEditorContextValue {
     /** Get the current document text */
     getValue: () => string;
@@ -166,6 +192,12 @@ interface CodeEditorContextValue {
     _maxHeight?: number;
     /** @internal — lines to band; see {@link CodeEditorProps.highlightLines}. */
     _highlightLines?: readonly number[];
+    /** @internal — accessible-name attributes for the textarea. */
+    _aria?: {
+        "aria-label"?: string;
+        "aria-labelledby"?: string;
+        "aria-describedby"?: string;
+    };
 }
 interface CodeEditorToolbarProps {
     children?: ReactNode;
@@ -199,7 +231,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, highlightLines, }: 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, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, }: CodeEditorProps): react.JSX.Element;
 declare namespace CodeEditorRoot {
     var displayName: string;
 }
@@ -214,7 +246,11 @@ declare const CodeEditor: typeof CodeEditorRoot & {
 declare function useCodeEditor(): CodeEditorContextValue;
 
 type MarkdownEditorMode = "split" | "edit" | "preview";
-interface MarkdownEditorProps {
+/**
+ * `aria-label` / `aria-labelledby` / `aria-describedby` name the editing
+ * textarea. Default name: "Markdown editor".
+ */
+interface MarkdownEditorProps extends EditorAriaProps {
     /** Controlled markdown value. */
     value?: string;
     /** Initial value (uncontrolled). */
@@ -265,7 +301,7 @@ interface MarkdownEditorProps {
  * <MarkdownEditor value={md} onValueChange={setMd} mode="split" minHeight={240} />
  * ```
  */
-declare function MarkdownEditor({ value, defaultValue, onValueChange, mode, theme, readOnly, lineNumbers, wordWrap, placeholder, minHeight, maxHeight, className, renderPreview, }: MarkdownEditorProps): react.JSX.Element;
+declare function MarkdownEditor({ value, defaultValue, onValueChange, mode, theme, readOnly, lineNumbers, wordWrap, placeholder, minHeight, maxHeight, className, renderPreview, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, }: MarkdownEditorProps): react.JSX.Element;
 declare namespace MarkdownEditor {
     var displayName: string;
 }
@@ -319,7 +355,11 @@ interface ResolveFileKindInput {
  */
 declare function resolveFileKind({ filename, mime }: ResolveFileKindInput): FileKind;
 
-interface FileViewerProps {
+/**
+ * `aria-label` / `aria-labelledby` / `aria-describedby` name the source view's
+ * textarea. Default name: the `filename`, else "File contents".
+ */
+interface FileViewerProps extends EditorAriaProps {
     /**
      * File name or path — used to detect the file kind / editor language, and as
      * a label / alt text. Pass `mime` too when you have it (it's preferred).
@@ -405,7 +445,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, line, column, highlightLines, minHeight, maxHeight, mediaProps, view, frameProps, document, 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, view, frameProps, document, className, style, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, }: FileViewerProps): react.JSX.Element;
 declare namespace FileViewer {
     var displayName: string;
 }
@@ -485,14 +525,6 @@ declare function diffRemovedColor(colors: ThemeColors): string;
  */
 declare function renderMarkdown(markdown: string): string;
 
-/**
- * Minimal, dependency-free Markdown tokenizer for editor highlighting. Line-based
- * for block constructs (fences, headings, blockquotes, list markers) plus a few
- * safe, non-overlapping inline spans (code, bold/italic, links). Good enough to
- * read structure at a glance — not a full CommonMark parse.
- */
-declare function tokenizeMarkdown(source: string): Token[];
-
 interface LanguageDefinition {
     /** Display name shown in UI (e.g., "JavaScript") */
     name: string;
@@ -551,4 +583,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 DocumentFormat, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type OfficeKind, type OfficeViewerOptions, type OfficeViewerProps, type ResolveFileKindInput, type ThemeDefinition, clearOfficeViewers, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, officeViewerFor, registerLanguage, registerOfficeViewer, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
+export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type DocumentFormat, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type OfficeKind, type OfficeViewerOptions, type OfficeViewerProps, type ResolveFileKindInput, type ThemeDefinition, clearOfficeViewers, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, officeViewerFor, registerLanguage, registerOfficeViewer, registerTheme, renderMarkdown, resolveFileKind, useCodeEditor, useCodeEditorInputTagAdapter };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { RefObject, ReactNode, CSSProperties, ComponentType } 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 { ThemeColors, DiffAnnotations, LineChangeType, Tokenizer } from '@particle-academy/fancy-file-commons';
+export { ThemeColors, Token, TokenType, Tokenizer, languageFromFilename, tokenizeMarkdown } from '@particle-academy/fancy-file-commons';
 import { MediaKind, MediaViewerProps, FauxClientProps, InputTagProps, InputTagTriggers, InputTagAdapter } from '@particle-academy/react-fancy';
 
 interface ThemeDefinition {
@@ -21,6 +21,11 @@ interface UseEditorEngineReturn {
     themeColors: ThemeColors;
     handleKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
     handleInput: () => void;
+    /**
+     * Ends the focus session: disarms Tab-indent so the next Tab into the editor
+     * moves focus rather than indenting. Wire to the textarea's `onBlur`.
+     */
+    handleBlur: () => void;
     handleScroll: () => void;
     handleSelect: () => void;
     /**
@@ -49,13 +54,22 @@ interface CodeEditorProps {
     onLanguageChange?: (lang: string) => void;
     /** Theme name: "light", "dark", "auto", or a custom registered name (default: "auto") */
     theme?: string;
-    /** Prevent editing (default: false) */
+    /**
+     * Prevent editing (default: false). Read-only editors still take every
+     * navigation key, and Tab / Shift+Tab move focus out.
+     */
     readOnly?: boolean;
     /** Show line numbers (default: true) */
     lineNumbers?: boolean;
     /** Enable word wrap (default: false) */
     wordWrap?: boolean;
-    /** Tab size in spaces (default: 2) */
+    /**
+     * Tab size in spaces (default: 2).
+     *
+     * Tab / Shift+Tab indent and dedent only once the user has edited in the
+     * current focus session; until then Tab moves focus like any other control,
+     * so keyboard users are never trapped (WCAG 2.1.2). Escape and blur disarm.
+     */
     tabSize?: number;
     /** Placeholder shown when empty */
     placeholder?: string;
@@ -88,7 +102,19 @@ interface CodeEditorProps {
      * marks. Requires `lineNumbers`.
      */
     diffBase?: string | null;
+    /**
+     * Accessible name of the editing surface. Lands on the `<textarea>` a person
+     * types into, not on a wrapper. Default "Code editor"; ignored when
+     * `aria-labelledby` is set.
+     */
+    "aria-label"?: string;
+    /** Id(s) of the element(s) naming the editing surface. Wins over `aria-label`. */
+    "aria-labelledby"?: string;
+    /** Id(s) of the element(s) describing the editing surface. */
+    "aria-describedby"?: string;
 }
+/** The accessible-name props every editor forwards to its textarea. */
+type EditorAriaProps = Pick<CodeEditorProps, "aria-label" | "aria-labelledby" | "aria-describedby">;
 interface CodeEditorContextValue {
     /** Get the current document text */
     getValue: () => string;
@@ -166,6 +192,12 @@ interface CodeEditorContextValue {
     _maxHeight?: number;
     /** @internal — lines to band; see {@link CodeEditorProps.highlightLines}. */
     _highlightLines?: readonly number[];
+    /** @internal — accessible-name attributes for the textarea. */
+    _aria?: {
+        "aria-label"?: string;
+        "aria-labelledby"?: string;
+        "aria-describedby"?: string;
+    };
 }
 interface CodeEditorToolbarProps {
     children?: ReactNode;
@@ -199,7 +231,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, highlightLines, }: 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, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, }: CodeEditorProps): react.JSX.Element;
 declare namespace CodeEditorRoot {
     var displayName: string;
 }
@@ -214,7 +246,11 @@ declare const CodeEditor: typeof CodeEditorRoot & {
 declare function useCodeEditor(): CodeEditorContextValue;
 
 type MarkdownEditorMode = "split" | "edit" | "preview";
-interface MarkdownEditorProps {
+/**
+ * `aria-label` / `aria-labelledby` / `aria-describedby` name the editing
+ * textarea. Default name: "Markdown editor".
+ */
+interface MarkdownEditorProps extends EditorAriaProps {
     /** Controlled markdown value. */
     value?: string;
     /** Initial value (uncontrolled). */
@@ -265,7 +301,7 @@ interface MarkdownEditorProps {
  * <MarkdownEditor value={md} onValueChange={setMd} mode="split" minHeight={240} />
  * ```
  */
-declare function MarkdownEditor({ value, defaultValue, onValueChange, mode, theme, readOnly, lineNumbers, wordWrap, placeholder, minHeight, maxHeight, className, renderPreview, }: MarkdownEditorProps): react.JSX.Element;
+declare function MarkdownEditor({ value, defaultValue, onValueChange, mode, theme, readOnly, lineNumbers, wordWrap, placeholder, minHeight, maxHeight, className, renderPreview, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, }: MarkdownEditorProps): react.JSX.Element;
 declare namespace MarkdownEditor {
     var displayName: string;
 }
@@ -319,7 +355,11 @@ interface ResolveFileKindInput {
  */
 declare function resolveFileKind({ filename, mime }: ResolveFileKindInput): FileKind;
 
-interface FileViewerProps {
+/**
+ * `aria-label` / `aria-labelledby` / `aria-describedby` name the source view's
+ * textarea. Default name: the `filename`, else "File contents".
+ */
+interface FileViewerProps extends EditorAriaProps {
     /**
      * File name or path — used to detect the file kind / editor language, and as
      * a label / alt text. Pass `mime` too when you have it (it's preferred).
@@ -405,7 +445,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, line, column, highlightLines, minHeight, maxHeight, mediaProps, view, frameProps, document, 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, view, frameProps, document, className, style, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, }: FileViewerProps): react.JSX.Element;
 declare namespace FileViewer {
     var displayName: string;
 }
@@ -485,14 +525,6 @@ declare function diffRemovedColor(colors: ThemeColors): string;
  */
 declare function renderMarkdown(markdown: string): string;
 
-/**
- * Minimal, dependency-free Markdown tokenizer for editor highlighting. Line-based
- * for block constructs (fences, headings, blockquotes, list markers) plus a few
- * safe, non-overlapping inline spans (code, bold/italic, links). Good enough to
- * read structure at a glance — not a full CommonMark parse.
- */
-declare function tokenizeMarkdown(source: string): Token[];
-
 interface LanguageDefinition {
     /** Display name shown in UI (e.g., "JavaScript") */
     name: string;
@@ -551,4 +583,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 DocumentFormat, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type OfficeKind, type OfficeViewerOptions, type OfficeViewerProps, type ResolveFileKindInput, type ThemeDefinition, clearOfficeViewers, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, officeViewerFor, registerLanguage, registerOfficeViewer, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
+export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type DocumentFormat, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type OfficeKind, type OfficeViewerOptions, type OfficeViewerProps, type ResolveFileKindInput, type ThemeDefinition, clearOfficeViewers, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, officeViewerFor, registerLanguage, registerOfficeViewer, registerTheme, renderMarkdown, resolveFileKind, useCodeEditor, useCodeEditorInputTagAdapter };