@coldsmirk/inkstone-react 0.8.2

package/dist/index.d.cts

@@ -0,0 +1,390 @@
+import { Extension } from "@codemirror/state";
+import { CodeMirrorLanguage, CodeMirrorLanguage as CodeMirrorLanguage$1, EditorContext, EditorContext as EditorContext$1, codeMirrorLanguages, normalizeContext, searchPhrasesZhCn } from "@coldsmirk/inkstone-codemirror";
+import { ReactNode, RefObject } from "react";
+import { EditorView } from "@codemirror/view";
+import { MonacoHostOptions, MonacoLanguage, MonacoLanguage as MonacoLanguage$1, MonacoUiLocale } from "@coldsmirk/inkstone-monaco";
+import { BeforeMount, OnMount } from "@monaco-editor/react";
+import { editor } from "monaco-editor";
+import { HighlighterCore } from "@coldsmirk/inkstone-core";
+
+//#region src/codemirror-editor.d.ts
+interface CodeMirrorEditorProps {
+  /**
+   * The controlled document text — external changes reconcile into the live editor
+   * without resetting the caret.
+   */
+  value: string;
+  onChange?: (value: string) => void;
+  /**
+   * Language id — lazily loads the matching CodeMirror grammar as its own chunk (only the
+   * selected language is fetched, never the whole catalog). For a language outside this set,
+   * or for parser options / mixed languages, pass your own support through `extensions`.
+   */
+  language?: CodeMirrorLanguage$1;
+  /**
+   * Render-context schema for variable / member autocomplete — currently consumed by the
+   * `minijinja` languages, where it makes `{{ }}` / `{% if %}` / `{% for x in %}` suggest the
+   * template's context variables and walk member access (`user.address.city`). Pass a JSON Schema
+   * (`{ schema }`, e.g. what Rust `schemars` derives) or a sample value (`{ sample }`); it updates
+   * reactively without recreating the editor. Memoize/hoist it — a new identity each render
+   * re-normalizes and re-dispatches. No effect on languages that don't read it.
+   */
+  context?: EditorContext$1;
+  placeholder?: string;
+  /**
+   * Soft-wrap long lines.
+   *
+   * @default false
+   */
+  lineWrapping?: boolean;
+  /**
+   * Show the line-number gutter. Fixed at creation, like `lineWrapping` / `placeholder`.
+   *
+   * @default false
+   */
+  showLineNumbers?: boolean;
+  /**
+   * Enable code folding (fold gutter + keymap). Fixed at creation; fold points come from the
+   * language, so set `language` too.
+   *
+   * @default false
+   */
+  folding?: boolean;
+  /**
+   * Turn native browser spell-check on. Off by default (CodeMirror's own default, right for
+   * code); enable for prose-grade documents like prompt templates. Fixed at creation.
+   *
+   * @default false
+   */
+  spellcheck?: boolean;
+  /**
+   * Enable in-editor search: Ctrl/Cmd-F opens a catppuccin-styled search/replace panel; F3 /
+   * Ctrl/Cmd-G cycle matches, Ctrl/Cmd-D selects the next occurrence, Alt-G jumps to a line.
+   * The panel speaks CodeMirror's stock English — set `locale="zh-cn"` (or pass
+   * `searchPhrasesZhCn` through `extensions`) for Simplified Chinese. Off by default —
+   * embedded fields rarely want a search UI. Fixed at creation.
+   *
+   * @default false
+   */
+  search?: boolean;
+  /**
+   * Editor font size in px, applied as a theme extension.
+   *
+   * @default 14
+   */
+  fontSize?: number;
+  /**
+   * Line height, applied as a theme extension on the scroller so content and gutters stay
+   * in step. Same convention as `<MonacoEditor>` (Monaco's own): values below 8 multiply the
+   * font size (e.g. `1.6` — CSS's unitless line-height), larger values are absolute pixels
+   * (e.g. `22`).
+   *
+   * @default 1.6
+   */
+  lineHeight?: number;
+  /**
+   * Tab width in spaces — sets both the displayed tab width (`EditorState.tabSize`) and the
+   * indent string inserted on Tab (`indentUnit`), so display and indentation stay in sync.
+   */
+  tabSize?: number;
+  /**
+   * Static extensions (language support, keymaps …), fixed for the editor's lifetime.
+   * Hoist the array — a new identity per render is ignored by design (create-once).
+   */
+  extensions?: Extension[];
+  /**
+   * Extensions swapped in place when the identity changes (theme, language config) —
+   * memoize with `useMemo` keyed on what actually changes. Layered after (and so able to
+   * override) inkstone's default catppuccin theme.
+   */
+  dynamicExtensions?: Extension[];
+  /**
+   * Use the dark catppuccin flavor (macchiato) instead of the light one (latte). The
+   * component never reads the OS `prefers-color-scheme`; wire this to your app's
+   * color-scheme state — same policy as `<MonacoEditor>`.
+   *
+   * @default false
+   */
+  dark?: boolean;
+  /**
+   * Locale for the phrase tables inkstone ships for CodeMirror's stock UI strings —
+   * currently the search / goto-line panel. Unlike Monaco's page-global locale, this is
+   * genuinely per-editor (`EditorState.phrases`) and swaps in place. Equivalent to passing
+   * `searchPhrasesZhCn` through `extensions`, which stays the framework-agnostic surface.
+   *
+   * @default "en"
+   */
+  locale?: "en" | "zh-cn";
+  /**
+   * Editor height — a number is treated as px. Sizes the editor box and hands overflow to
+   * the scroller; omit to grow with content.
+   */
+  height?: string | number;
+  /**
+   * Editor width — a number is treated as px. Omit to fill the container.
+   */
+  width?: string | number;
+  className?: string;
+  /**
+   * Runs once after the editor is created, with the CodeMirror `EditorView` — the imperative
+   * handle for focus, dispatch, scrolling, selection, etc. This is CodeMirror's analog of
+   * Monaco's `onMount`. Monaco's `loading` / `beforeMount` have no counterpart here: the
+   * editor mounts synchronously (no host or editor chunk to await — only the optional
+   * `language` grammar streams in behind an already-usable editor), and pre-creation setup is
+   * the `extensions` prop rather than a global instance to configure.
+   */
+  onMount?: (view: EditorView) => void;
+  /**
+   * Called when the editor gains focus.
+   */
+  onFocus?: () => void;
+  /**
+   * Called when the editor loses focus.
+   */
+  onBlur?: () => void;
+}
+/**
+ * A controlled CodeMirror 6 document editor: the standard document extension bundle
+ * (line numbers, history, brackets, completion UI — see `documentExtensions`) plus the
+ * create-once / reconcile-in-place plumbing of `ControlledEditorHost`, exposed as a plain
+ * React component.
+ *
+ * Ships the catppuccin theme by default (latte / macchiato, flipped by `dark`) and takes
+ * `height` / `width` for sizing — parity with `<MonacoEditor>`. Bring your own language
+ * support via `extensions`; a theme passed through `dynamicExtensions` overrides the default.
+ */
+declare function CodeMirrorEditor({
+  value,
+  onChange,
+  language,
+  context,
+  placeholder,
+  lineWrapping,
+  showLineNumbers,
+  folding,
+  spellcheck,
+  search,
+  extensions,
+  dynamicExtensions,
+  dark,
+  locale,
+  height,
+  width,
+  fontSize,
+  lineHeight,
+  tabSize,
+  className,
+  onMount,
+  onFocus,
+  onBlur
+}: CodeMirrorEditorProps): ReactNode;
+//#endregion
+//#region src/monaco-editor.d.ts
+/**
+ * Baseline construction options shared by every inkstone Monaco editor: no minimap, compact
+ * code type, in-place layout tracking, widgets floated above clipping containers, completion
+ * tuned for API-assisted editing, thin scrollbars, and an embedded-friendly find widget.
+ * Spread these to extend rather than replace: `options={{ ...DEFAULT_MONACO_OPTIONS, wordWrap: "on" }}`.
+ */
+declare const DEFAULT_MONACO_OPTIONS: editor.IStandaloneEditorConstructionOptions;
+interface MonacoEditorProps {
+  /**
+   * The controlled document text.
+   */
+  value: string;
+  onChange?: (value: string) => void;
+  /**
+   * Monaco language id. Built-in ids autocomplete; any custom-registered id is also accepted.
+   *
+   * @default "javascript"
+   */
+  language?: MonacoLanguage$1;
+  /**
+   * Render with the dark theme. The component never reads the OS `prefers-color-scheme`;
+   * wire this to your app's color-scheme state.
+   *
+   * @default false
+   */
+  dark?: boolean;
+  /**
+   * UI locale for Monaco's built-in chrome (context menu, find widget, command palette …).
+   * Unlike everything else on this component, the locale is **page-global and locked by the
+   * first editor to mount** — Monaco resolves its UI strings once, at module evaluation — so
+   * later editors with a different value are ignored. Overrides `hostOptions.locale` (the
+   * same knob on the framework-agnostic host layer).
+   *
+   * @default "en"
+   */
+  locale?: MonacoUiLocale;
+  /**
+   * Placeholder shown while the document is empty. Maps to Monaco's native `placeholder`
+   * editor option (0.47+); an explicit `options.placeholder` still wins.
+   */
+  placeholder?: string;
+  /**
+   * Soft-wrap long lines (Monaco `wordWrap`).
+   *
+   * @default false
+   */
+  lineWrapping?: boolean;
+  /**
+   * Show the line-number gutter (Monaco `lineNumbers`). For relative/interval modes pass an
+   * explicit `options.lineNumbers`.
+   *
+   * @default false
+   */
+  showLineNumbers?: boolean;
+  /**
+   * Editor font size in px (Monaco `fontSize`). Omit to keep the inkstone default (14).
+   */
+  fontSize?: number;
+  /**
+   * Line height (Monaco `lineHeight`, and its convention): values below 8 multiply the font
+   * size (e.g. `1.6`), larger values are absolute pixels (e.g. `22`). `<CodeMirrorEditor>`
+   * mirrors the same semantics. Omit to keep the inkstone default (1.6).
+   */
+  lineHeight?: number;
+  /**
+   * Tab width in spaces (Monaco `tabSize`).
+   *
+   * @default 2
+   */
+  tabSize?: number;
+  /**
+   * Enable code folding (fold gutter + fold ranges). Unifies the toggle with
+   * `<CodeMirrorEditor>`; note Monaco folds by default, so this turns its folding off unless
+   * set.
+   *
+   * @default false
+   */
+  folding?: boolean;
+  /**
+   * Disable Monaco's right-click context menu (`contextmenu: false`). Right-clicks then fall
+   * through to the browser, so its native menu applies — intercept `contextmenu` on a
+   * wrapping element to suppress that as well.
+   *
+   * @default false
+   */
+  disableContextMenu?: boolean;
+  /**
+   * Swallow the find/replace widget's keyboard entries — Ctrl/Cmd+F (find), Ctrl+H and
+   * Cmd+Alt+F (replace). Scoped to this editor via a context key: the standalone keybinding
+   * service is page-global, so an unscoped rule would rewire every editor on the page.
+   * Fixed at creation.
+   *
+   * @default false
+   */
+  disableFind?: boolean;
+  /**
+   * Swallow the command palette's keyboard entry, F1 — Monaco never binds Ctrl+Shift+P
+   * (that is a VS Code binding). While the context menu is enabled, its "Command Palette"
+   * item still opens the palette; pair with {@link disableContextMenu} to remove every
+   * entry point. Fixed at creation.
+   *
+   * @default false
+   */
+  disableCommandPalette?: boolean;
+  /**
+   * Model path — give each logically distinct document its own so view state (cursor,
+   * folds) survives remounts.
+   */
+  path?: string;
+  height?: string | number;
+  width?: string | number;
+  className?: string;
+  /**
+   * Extra construction options, merged over {@link DEFAULT_MONACO_OPTIONS}.
+   */
+  options?: editor.IStandaloneEditorConstructionOptions;
+  /**
+   * Host bring-up options (UI locale, language workers). The Monaco host is a process-wide
+   * singleton, so the first mounted editor wins and later values are ignored.
+   */
+  hostOptions?: MonacoHostOptions;
+  /**
+   * Shown while the host, highlighter, and editor chunk load.
+   *
+   * @default "Loading editor…"
+   */
+  loading?: ReactNode;
+  /**
+   * Shown when the Monaco host fails to load (e.g. a stale chunk 404 after a redeploy).
+   * The failure is not cached by the host singleton, so a fresh mount retries.
+   *
+   * @default "Editor failed to load"
+   */
+  failure?: ReactNode;
+  /**
+   * Runs after inkstone's own pre-mount setup (Shiki theme registration).
+   */
+  beforeMount?: BeforeMount;
+  onMount?: OnMount;
+  /**
+   * Called when the editor's text area gains focus (Monaco `onDidFocusEditorText`).
+   */
+  onFocus?: () => void;
+  /**
+   * Called when the editor's text area loses focus (Monaco `onDidBlurEditorText`).
+   */
+  onBlur?: () => void;
+}
+/**
+ * A preconfigured, offline Monaco editor: bundled workers (no CDN), Shiki catppuccin
+ * highlighting with light/dark switching, and sensible document defaults — drop it in with
+ * `value` / `onChange` and everything else is wired. The UI speaks Monaco's stock English;
+ * pass `hostOptions={{ locale: "zh-cn" }}` for the official Simplified-Chinese chrome.
+ *
+ * Mounting is gated on the Monaco host and the Shiki highlighter so the first paint already
+ * has the right theme; if the highlighter fails to load, the editor falls back to Monaco's
+ * built-in themes and stays usable.
+ *
+ * Do not `import "monaco-editor"` statically elsewhere in the app — that would evaluate
+ * Monaco before its UI locale is set (see `ensureMonacoHost`). Type-only imports are fine.
+ */
+declare function MonacoEditor({
+  value,
+  onChange,
+  language,
+  dark,
+  locale,
+  placeholder,
+  lineWrapping,
+  showLineNumbers,
+  folding,
+  disableContextMenu,
+  disableFind,
+  disableCommandPalette,
+  fontSize,
+  lineHeight,
+  tabSize,
+  path,
+  height,
+  width,
+  className,
+  options,
+  hostOptions,
+  loading,
+  failure,
+  beforeMount,
+  onMount,
+  onFocus,
+  onBlur
+}: MonacoEditorProps): ReactNode;
+//#endregion
+//#region src/use-shiki-highlighter.d.ts
+type ShikiState = "loading" | "ready" | "failed";
+/**
+ * Load the shared Shiki highlighter and expose its lifecycle to gate editor mounting:
+ * waiting for `ready` before creating the editor avoids a default-theme flash (and the
+ * "theme not found" console error) on first paint; on `failed` the caller falls back to
+ * the engine's built-in theme so the editor stays usable.
+ *
+ * `highlighterRef` is for pre-mount hooks (Monaco `beforeMount`) that must read the
+ * instance synchronously before the editor is created.
+ */
+declare function useShikiHighlighter(): {
+  state: ShikiState;
+  highlighterRef: RefObject<HighlighterCore | null>;
+};
+//#endregion
+export { CodeMirrorEditor, type CodeMirrorEditorProps, type CodeMirrorLanguage, DEFAULT_MONACO_OPTIONS, type EditorContext, MonacoEditor, type MonacoEditorProps, type MonacoLanguage, type ShikiState, codeMirrorLanguages, normalizeContext, searchPhrasesZhCn, useShikiHighlighter };