@coldsmirk/inkstone-sql 0.13.0

package/dist/monaco.d.ts

@@ -0,0 +1,31 @@
+import { t as SqlAssist } from "./assist-gLTZKSD3.js";
+import * as monacoEditor from "monaco-editor";
+import { IDisposable } from "monaco-editor";
+
+//#region src/monaco.d.ts
+/**
+ * The monaco module itself, as `onMount` hands it over — typed structurally so this entry needs
+ * no dependency beyond `monaco-editor`'s own types.
+ */
+type MonacoModule = typeof monacoEditor;
+interface SqlLanguageHooks {
+  /**
+   * The assist as it stands right now — read per request rather than captured, so switching
+   * connections swaps the schema behind every feature without touching Monaco's registry.
+   */
+  assist: () => SqlAssist | null;
+  /**
+   * The dialect could not parse the statement, so nothing was reformatted. The host says so:
+   * a deliberate keystroke that changes nothing needs to explain itself.
+   */
+  onFormatRefused: () => void;
+}
+/**
+ * Register completion, hover, signature help and formatting for one model. The disposables are
+ * the caller's to hold: Monaco's registry outlives any editor, and a provider left behind would
+ * answer for a model that no longer exists. `languageId` is the language the model is registered
+ * under — the stock `"sql"` unless the host runs a dialect id of its own.
+ */
+declare function registerSqlLanguage(monaco: MonacoModule, modelPath: string, hooks: SqlLanguageHooks, languageId?: string): IDisposable[];
+//#endregion
+export { MonacoModule, SqlLanguageHooks, registerSqlLanguage };

package/dist/monaco.js

@@ -0,0 +1,128 @@
+//#region src/monaco.ts
+function itemKinds(monaco) {
+	const kinds = monaco.languages.CompletionItemKind;
+	return {
+		keyword: kinds.Keyword,
+		function: kinds.Function,
+		schema: kinds.Module,
+		table: kinds.Struct,
+		view: kinds.Interface,
+		column: kinds.Field,
+		snippet: kinds.Snippet
+	};
+}
+const FORMATTING_KEY = Symbol.for("coldsmirk.inkstone.sql.formattingRegistry");
+function formattingLedgers(monaco) {
+	const holder = globalThis;
+	const registries = holder[FORMATTING_KEY] ?? /* @__PURE__ */ new WeakMap();
+	holder[FORMATTING_KEY] = registries;
+	const existing = registries.get(monaco);
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Map();
+	registries.set(monaco, created);
+	return created;
+}
+function registerFormatting(monaco, languageId, modelPath, hooks) {
+	const ledgers = formattingLedgers(monaco);
+	let ledger = ledgers.get(languageId);
+	if (ledger === void 0) {
+		const byPath = /* @__PURE__ */ new Map();
+		ledger = {
+			hooks: byPath,
+			registration: monaco.languages.registerDocumentFormattingEditProvider(languageId, { provideDocumentFormattingEdits: async (model) => {
+				const owner = byPath.get(model.uri.toString());
+				const assist = owner?.assist() ?? null;
+				const text = model.getValue();
+				if (owner === void 0 || assist === null || text.trim() === "") return [];
+				const formatted = await assist.format(text);
+				if (formatted === null) {
+					owner.onFormatRefused();
+					return [];
+				}
+				return formatted === text ? [] : [{
+					range: model.getFullModelRange(),
+					text: formatted
+				}];
+			} })
+		};
+		ledgers.set(languageId, ledger);
+	}
+	const entered = ledger;
+	entered.hooks.set(modelPath, hooks);
+	return { dispose: () => {
+		entered.hooks.delete(modelPath);
+		if (entered.hooks.size === 0) {
+			entered.registration.dispose();
+			ledgers.delete(languageId);
+		}
+	} };
+}
+function registerSqlLanguage(monaco, modelPath, hooks, languageId = "sql") {
+	const kinds = itemKinds(monaco);
+	const path = monaco.Uri.parse(modelPath).toString();
+	const answering = (model) => model.uri.toString() === path ? hooks.assist() : null;
+	return [
+		monaco.languages.registerCompletionItemProvider(languageId, {
+			triggerCharacters: ["."],
+			provideCompletionItems: async (model, position) => {
+				const assist = answering(model);
+				if (assist === null) return { suggestions: [] };
+				const candidates = await assist.complete(model.getValue(), model.getOffsetAt(position));
+				const word = model.getWordUntilPosition(position);
+				return { suggestions: candidates.map((candidate, index) => {
+					return {
+						label: candidate.label,
+						kind: kinds[candidate.kind],
+						insertText: candidate.insertText,
+						insertTextRules: candidate.snippet ? monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet : void 0,
+						detail: candidate.detail,
+						documentation: candidate.documentation,
+						range: new monaco.Range(position.lineNumber, Math.max(1, word.startColumn - (candidate.replace ?? 0)), position.lineNumber, word.endColumn),
+						sortText: `${candidate.sortGroup}:${String(index).padStart(5, "0")}`
+					};
+				}) };
+			}
+		}),
+		monaco.languages.registerHoverProvider(languageId, { provideHover: async (model, position) => {
+			const assist = answering(model);
+			if (assist === null) return null;
+			const card = await assist.hover(model.getValue(), model.getOffsetAt(position));
+			if (card === null) return null;
+			const from = model.getPositionAt(card.from);
+			const to = model.getPositionAt(card.to);
+			return {
+				range: new monaco.Range(from.lineNumber, from.column, to.lineNumber, to.column),
+				contents: card.markdown.map((value) => {
+					return { value };
+				})
+			};
+		} }),
+		monaco.languages.registerSignatureHelpProvider(languageId, {
+			signatureHelpTriggerCharacters: ["(", ","],
+			signatureHelpRetriggerCharacters: [","],
+			provideSignatureHelp: async (model, position) => {
+				const assist = answering(model);
+				if (assist === null) return null;
+				const help = await assist.signature(model.getValue(), model.getOffsetAt(position));
+				if (help === null) return null;
+				return {
+					value: {
+						signatures: [{
+							label: help.label,
+							documentation: help.documentation,
+							parameters: help.parameters.map((span) => {
+								return { label: span };
+							})
+						}],
+						activeSignature: 0,
+						activeParameter: help.active
+					},
+					dispose: () => void 0
+				};
+			}
+		}),
+		registerFormatting(monaco, languageId, path, hooks)
+	];
+}
+//#endregion
+export { registerSqlLanguage };

package/dist/react.d.ts

@@ -0,0 +1,158 @@
+import { t as SqlAssist } from "./assist-gLTZKSD3.js";
+import { MonacoModule } from "./monaco.js";
+import { ReactNode } from "react";
+import { editor } from "monaco-editor";
+
+//#region src/react.d.ts
+/**
+ * What a host needs to reach into the editor for: inserting at the caret (a schema tree is an
+ * input device, not a browser), and reformatting from a toolbar — which goes through Monaco's own
+ * formatting action, so the button and `Shift+Alt+F` are one path and one undo.
+ */
+interface SqlEditorHandle {
+  insert: (text: string) => void;
+  format: () => void;
+}
+/**
+ * Where the operator is in the document, in offsets — everything a host needs to decide which
+ * statement a run should send, and nothing about SQL. `from` and `to` are the selection's own
+ * bounds and are equal where nothing is selected: a caret is a selection of nothing.
+ *
+ * It rides with the text rather than beside it because the two must belong to the same instant.
+ * The controlled `value` is one React render behind the keystroke that triggered a run, and a
+ * console must run the statement the operator is looking at.
+ */
+interface SqlCaret {
+  text: string;
+  from: number;
+  to: number;
+}
+interface SqlEditorProps {
+  value: string;
+  onChange: (value: string) => void;
+  /**
+   * Render with the dark theme. Like every inkstone editor, the component never reads the OS
+   * `prefers-color-scheme`; wire this to the app's color-scheme state.
+   *
+   * @default false
+   */
+  dark?: boolean;
+  /**
+   * Editor height in px, or `"fill"` to consume the parent's resolved height (the parent must be
+   * a `min-height: 0` flex item). Monaco's loading placeholder is `height: 100%`, so a height
+   * that resolves to nothing collapses the field to one line while the editor loads.
+   */
+  height?: number | "fill";
+  /**
+   * Editor font size in px. Omit to keep the inkstone default.
+   */
+  fontSize?: number;
+  /**
+   * UI locale for Monaco's built-in chrome — page-global and locked by the first editor to
+   * mount, exactly as on `<MonacoEditor>`.
+   */
+  locale?: "en" | "zh-cn";
+  placeholder?: string;
+  /**
+   * The editor's accessible name, set on Monaco's own input surface — several SQL editors on one
+   * page are indistinguishable to assistive tech without one.
+   */
+  ariaLabel: string;
+  /**
+   * The Monaco language id the model registers under.
+   *
+   * @default "sql"
+   */
+  languageId?: string;
+  /**
+   * Shown while the Monaco host loads / when it fails to load — passed through to
+   * `<MonacoEditor>`, whose English defaults apply when omitted.
+   */
+  loading?: ReactNode;
+  failure?: ReactNode;
+  /**
+   * Ctrl/Cmd-Enter — the run key, bound inside the editor because that is where the operator's
+   * hands are. It is handed the editor's live caret, from which the host works out what to send.
+   * Read through a ref at every press, so it always runs against the connection the *current*
+   * render is bound to.
+   */
+  onRun?: (caret: SqlCaret) => void;
+  /**
+   * The label the run action shows in Monaco's own chrome (command palette, context menu).
+   *
+   * @default "Run statement"
+   */
+  runActionLabel?: string;
+  /**
+   * The caret moved, or the text under it changed. The host tracks it to show what a run would
+   * send; the run key does not depend on that tracking having caught up.
+   */
+  onCaret?: (caret: SqlCaret) => void;
+  /**
+   * The span to mark as the one a run would send. Null leaves the gutter clean, which is the
+   * right answer while there is nothing to choose between.
+   */
+  highlight?: {
+    from: number;
+    to: number;
+  } | null;
+  /**
+   * The class the highlight's line decoration carries. The host owns its stylesheet — a
+   * left-margin bar reads well, because it says which statement without touching a single colour
+   * the syntax already assigned.
+   *
+   * @default "inkstone-sql-runnable"
+   */
+  highlightClassName?: string;
+  /**
+   * The dialect could not parse the statement, so the format action changed nothing. The host
+   * says so — a deliberate keystroke that changes nothing needs to explain itself.
+   */
+  onFormatRefused?: () => void;
+  onReady?: (handle: SqlEditorHandle) => void;
+  /**
+   * Runs after this component's own mount wiring, with the live editor and the monaco module —
+   * the escape hatch for host-specific concerns (focus shields, extra actions).
+   */
+  onMount?: (instance: editor.IStandaloneCodeEditor, monaco: MonacoModule) => void;
+  /**
+   * What the editor's language features answer from — the schema and dialect of the connection
+   * being edited (`createSqlAssist`). Read through a ref at every request, so the host can swap
+   * it without re-registering anything with Monaco.
+   */
+  assist?: SqlAssist;
+}
+/**
+ * The SQL editing surface: Monaco in `sql`, highlighted by the same shared Shiki grammar every
+ * other inkstone surface uses. It is deliberately not a script editor — a TypeScript language
+ * service and an ambient profile have no meaning for a vendor's SQL. Its language features are
+ * the host's: the `assist` knows the catalog and the dialect and this component only wires it to
+ * Monaco (`registerSqlLanguage`) — it never guesses at SQL itself.
+ *
+ * The editor draws no chrome of its own: it is a band of its host's surface, and the separation
+ * is the host's hairline rules — a border here would dress a pane up as a form input.
+ */
+declare function SqlEditor({
+  value,
+  onChange,
+  dark,
+  height,
+  fontSize,
+  locale,
+  placeholder,
+  ariaLabel,
+  languageId,
+  loading,
+  failure,
+  onRun,
+  runActionLabel,
+  onCaret,
+  highlight,
+  highlightClassName,
+  onFormatRefused,
+  onReady,
+  onMount,
+  assist
+}: SqlEditorProps): import("react").JSX.Element;
+//#endregion
+export { SqlCaret, SqlEditor, SqlEditorHandle, SqlEditorProps };

package/dist/react.js

@@ -0,0 +1,135 @@
+import { registerSqlLanguage } from "./monaco.js";
+import { MonacoEditor } from "@coldsmirk/inkstone-react/monaco";
+import { useEffect, useInsertionEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react.tsx
+const EDITOR_ID_KEY = Symbol.for("coldsmirk.inkstone.sql.editorId");
+function nextEditorId() {
+	const holder = globalThis;
+	const id = holder[EDITOR_ID_KEY] ?? 0;
+	holder[EDITOR_ID_KEY] = id + 1;
+	return id;
+}
+const FORMAT_CHORD_CONTEXT_KEY = "inkstoneSqlFormatChord";
+function useLatest(value) {
+	const ref = useRef(value);
+	useInsertionEffect(() => {
+		ref.current = value;
+	});
+	return ref;
+}
+function caretOf(instance) {
+	const model = instance.getModel();
+	const selection = instance.getSelection();
+	if (model === null || selection === null) return {
+		text: "",
+		from: 0,
+		to: 0
+	};
+	return {
+		text: model.getValue(),
+		from: model.getOffsetAt(selection.getStartPosition()),
+		to: model.getOffsetAt(selection.getEndPosition())
+	};
+}
+function monacoRange(model, span) {
+	const from = model.getPositionAt(span.from);
+	const to = model.getPositionAt(span.to);
+	return {
+		startLineNumber: from.lineNumber,
+		startColumn: from.column,
+		endLineNumber: to.lineNumber,
+		endColumn: to.column
+	};
+}
+function SqlEditor({ value, onChange, dark = false, height = 200, fontSize, locale, placeholder, ariaLabel, languageId = "sql", loading, failure, onRun, runActionLabel = "Run statement", onCaret, highlight = null, highlightClassName = "inkstone-sql-runnable", onFormatRefused, onReady, onMount, assist }) {
+	const [modelPath] = useState(() => `file:///inkstone-sql/${nextEditorId()}.sql`);
+	const bindings = useRef([]);
+	const assistRef = useLatest(assist ?? null);
+	const formatRefusedRef = useLatest(onFormatRefused);
+	const runRef = useLatest(onRun);
+	const caretChangedRef = useLatest(onCaret);
+	const readyRef = useLatest(onReady);
+	const mountRef = useLatest(onMount);
+	const instance = useRef(null);
+	const marked = useRef(null);
+	const [mounted, setMounted] = useState(false);
+	useEffect(() => {
+		const model = instance.current?.getModel();
+		if (model === null || model === void 0) return;
+		marked.current?.clear();
+		marked.current = highlight === null ? null : instance.current.createDecorationsCollection([{
+			range: monacoRange(model, highlight),
+			options: {
+				linesDecorationsClassName: highlightClassName,
+				isWholeLine: true
+			}
+		}]);
+	}, [
+		highlight,
+		highlightClassName,
+		mounted
+	]);
+	useEffect(() => () => {
+		for (const binding of bindings.current) binding.dispose();
+		bindings.current = [];
+	}, []);
+	const fill = height === "fill";
+	return /* @__PURE__ */ jsx("div", {
+		style: fill ? {
+			height: "100%",
+			minHeight: 0
+		} : { height },
+		children: /* @__PURE__ */ jsx(MonacoEditor, {
+			showLineNumbers: true,
+			dark,
+			failure,
+			fontSize,
+			height: fill ? "100%" : height,
+			language: languageId,
+			loading,
+			locale,
+			path: modelPath,
+			placeholder,
+			value,
+			options: {
+				ariaLabel,
+				suggest: { snippetsPreventQuickSuggestions: false }
+			},
+			onChange,
+			onMount: (live, monaco) => {
+				instance.current = live;
+				live.createContextKey(FORMAT_CHORD_CONTEXT_KEY, true);
+				bindings.current.push(live.onDidChangeCursorSelection(() => caretChangedRef.current?.(caretOf(live))), live.addAction({
+					id: "inkstone-sql.run",
+					label: runActionLabel,
+					keybindings: [monaco.KeyMod.CtrlCmd | monaco.KeyCode.Enter],
+					run: (current) => runRef.current?.(caretOf(current))
+				}), monaco.editor.addKeybindingRule({
+					keybinding: monaco.KeyMod.Shift | monaco.KeyMod.Alt | monaco.KeyCode.KeyF,
+					command: "editor.action.formatDocument",
+					when: `${FORMAT_CHORD_CONTEXT_KEY} && editorTextFocus && !editorReadonly`
+				}), ...registerSqlLanguage(monaco, modelPath, {
+					assist: () => assistRef.current,
+					onFormatRefused: () => formatRefusedRef.current?.()
+				}, languageId));
+				readyRef.current?.({
+					format: () => void live.getAction("editor.action.formatDocument")?.run(),
+					insert: (text) => {
+						const selection = live.getSelection();
+						if (selection) live.executeEdits("inkstone-sql-insert", [{
+							range: selection,
+							text,
+							forceMoveMarkers: true
+						}]);
+						live.focus();
+					}
+				});
+				mountRef.current?.(live, monaco);
+				setMounted(true);
+			}
+		})
+	});
+}
+//#endregion
+export { SqlEditor };

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@coldsmirk/inkstone-sql",
+  "version": "0.13.0",
+  "description": "Schema-aware SQL editing intelligence for Monaco: lexical statement reading under per-dialect noise profiles, catalog-driven completion/hover/signature help, unified-placeholder awareness, formatting, and a drop-in React SQL editor.",
+  "keywords": [
+    "sql",
+    "monaco",
+    "completion",
+    "editor",
+    "autocomplete",
+    "dialect"
+  ],
+  "homepage": "https://github.com/coldsmirk/inkstone/tree/main/packages/sql#readme",
+  "bugs": "https://github.com/coldsmirk/inkstone/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coldsmirk/inkstone.git",
+    "directory": "packages/sql"
+  },
+  "license": "UNLICENSED",
+  "author": {
+    "name": "Venus"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./monaco": {
+      "types": "./dist/monaco.d.ts",
+      "default": "./dist/monaco.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "sql-formatter": "^15.8.2"
+  },
+  "devDependencies": {
+    "monaco-editor": "^0.55.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "@coldsmirk/inkstone-react": "^0.13.0"
+  },
+  "peerDependencies": {
+    "monaco-editor": "^0.55.1",
+    "react": ">=19",
+    "@coldsmirk/inkstone-react": "^0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "@coldsmirk/inkstone-react": {
+      "optional": true
+    },
+    "monaco-editor": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}