@particle-academy/fancy-code 0.16.0 → 0.17.0

package/dist/index.d.cts

@@ -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;
 }

package/dist/index.d.ts

@@ -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;
 }

package/dist/index.js

@@ -41,7 +41,8 @@ function CodeEditorPanel({ className }) {
     _diffAnnotations: diffAnnotations,
     _maxHeight,
     _minHeight,
-    _highlightLines: highlightLines
+    _highlightLines: highlightLines,
+    _aria: aria
   } = useCodeEditor();
   const lineNumberElements = useMemo(() => {
     if (!engine || !lineNumbers) return null;
@@ -131,6 +132,7 @@ function CodeEditorPanel({ className }) {
     themeColors,
     handleKeyDown,
     handleInput,
+    handleBlur,
     handleScroll,
     handleSelect,
     scrollTop,
@@ -203,8 +205,12 @@ function CodeEditorPanel({ className }) {
             "textarea",
             {
               ref: textareaRef,
+              "aria-label": aria?.["aria-label"],
+              "aria-labelledby": aria?.["aria-labelledby"],
+              "aria-describedby": aria?.["aria-describedby"],
               className: cn(
-                "relative m-0 block resize-none border-none bg-transparent p-2.5 text-[13px] leading-[1.5] text-transparent outline-none",
+                "relative m-0 block resize-none border-none bg-transparent p-2.5 text-[13px] leading-[1.5] text-transparent",
+                "focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[color:var(--fancy-focus,var(--color-blue-500))] dark:focus-visible:ring-[color:var(--fancy-focus-dark,var(--color-blue-400))]",
                 wordWrap ? "w-full" : "min-w-full"
               ),
               style: {
@@ -221,6 +227,7 @@ function CodeEditorPanel({ className }) {
               readOnly,
               onKeyDown: handleKeyDown,
               onInput: handleInput,
+              onBlur: handleBlur,
               onScroll: handleScroll,
               onSelect: handleSelect,
               onClick: handleSelect
@@ -482,6 +489,7 @@ function useEditorEngine({
   const [scrollTop, setScrollTop] = useState(0);
   const [scrollLeft, setScrollLeft] = useState(0);
   const [activeLine, setActiveLine] = useState(1);
+  const tabArmedRef = useRef(false);
   const themeColors = useMemo(() => {
     const def = getTheme(theme);
     return def?.colors ?? DEFAULT_COLORS;
@@ -542,6 +550,7 @@ function useEditorEngine({
   const handleInput = useCallback(() => {
     const ta = textareaRef.current;
     if (!ta) return;
+    tabArmedRef.current = true;
     onChangeRef.current?.(ta.value);
     autoResize();
     updateCursorInfo();
@@ -577,14 +586,19 @@ function useEditorEngine({
     },
     [updateCursorInfo]
   );
+  const handleBlur = useCallback(() => {
+    tabArmedRef.current = false;
+  }, []);
   const handleKeyDown = useCallback(
     (e) => {
       if (readOnly) {
-        if (e.key === "c" && (e.metaKey || e.ctrlKey)) return;
-        if (e.key === "a" && (e.metaKey || e.ctrlKey)) return;
-        e.preventDefault();
         return;
       }
+      if (e.key === "Escape") {
+        tabArmedRef.current = false;
+        return;
+      }
+      if (e.key === "Tab" && !tabArmedRef.current) return;
       if (e.key === "Tab") {
         e.preventDefault();
         const ta = e.currentTarget;
@@ -633,6 +647,7 @@ function useEditorEngine({
       }
       if (e.key === "Enter") {
         e.preventDefault();
+        tabArmedRef.current = true;
         const ta = e.currentTarget;
         const start = ta.selectionStart;
         const end = ta.selectionEnd;
@@ -661,6 +676,7 @@ function useEditorEngine({
     themeColors,
     handleKeyDown,
     handleInput,
+    handleBlur,
     handleScroll,
     handleSelect,
     revealLine,
@@ -701,8 +717,19 @@ function CodeEditorRoot({
   cursorLine,
   cursorColumn,
   diffBase,
-  highlightLines
+  highlightLines,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy
 }) {
+  const aria = useMemo(
+    () => ({
+      "aria-label": ariaLabelledBy ? void 0 : ariaLabel ?? "Code editor",
+      "aria-labelledby": ariaLabelledBy,
+      "aria-describedby": ariaDescribedBy
+    }),
+    [ariaLabel, ariaLabelledBy, ariaDescribedBy]
+  );
   const [currentValue, setCurrentValue] = useControllableState(valueProp, defaultValue, onChange);
   const diffAnnotations = useMemo(
     () => diffBase == null ? null : annotateLines(diffBase, currentValue),
@@ -795,9 +822,10 @@ function CodeEditorRoot({
       _engineReturn: engineReturn,
       _minHeight: minHeight,
       _maxHeight: maxHeight,
-      _highlightLines: highlightLines
+      _highlightLines: highlightLines,
+      _aria: aria
     }),
-    [engineReturn, currentValue, currentLanguage, setLanguage, resolvedTheme, readOnly, showLineNumbers, isWordWrap, tabSizeProp, cursorPosition, selectionLength, setCurrentValue, placeholder, diffAnnotations, minHeight, maxHeight, highlightLines]
+    [engineReturn, currentValue, currentLanguage, setLanguage, resolvedTheme, readOnly, showLineNumbers, isWordWrap, tabSizeProp, cursorPosition, selectionLength, setCurrentValue, placeholder, diffAnnotations, minHeight, maxHeight, highlightLines, aria]
   );
   return /* @__PURE__ */ jsx(CodeEditorContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsx(
     "div",
@@ -833,7 +861,10 @@ function MarkdownEditor({
   minHeight,
   maxHeight,
   className,
-  renderPreview
+  renderPreview,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy
 }) {
   const [content, setContent] = useControllableState(value, defaultValue, onValueChange);
   const showEditor = mode !== "preview";
@@ -858,6 +889,9 @@ function MarkdownEditor({
             placeholder,
             minHeight,
             maxHeight,
+            "aria-label": ariaLabel ?? "Markdown editor",
+            "aria-labelledby": ariaLabelledBy,
+            "aria-describedby": ariaDescribedBy,
             children: /* @__PURE__ */ jsx(CodeEditor.Panel, {})
           }
         ) }),
@@ -959,7 +993,10 @@ function FileViewer({
   frameProps,
   document,
   className,
-  style
+  style,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy
 }) {
   const resolved = fileKind ?? resolveFileKind({ filename, mime });
   if (resolved.kind === "document" && view === "rendered" && readOnly && line == null) {
@@ -1053,6 +1090,9 @@ function FileViewer({
           cursorLine: line,
           cursorColumn: column,
           highlightLines: highlightLines ?? (line != null ? [line] : void 0),
+          "aria-label": ariaLabel ?? filename ?? "File contents",
+          "aria-labelledby": ariaLabelledBy,
+          "aria-describedby": ariaDescribedBy,
           children: /* @__PURE__ */ jsx(CodeEditor.Panel, {})
         }
       )