@stepcode/codemirror 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 rolandoandrade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @stepcode/codemirror
+
+CodeMirror 6 language support for [StepCode](https://github.com/RolandoAndrade/stepcode),
+built on the same parser and checker the runtime uses, plus the editor-side debugging
+extensions. No worker, no interpreter: a host wires those.
+
+```ts
+import { defaultHighlightStyle, syntaxHighlighting } from '@codemirror/language'
+import { lintGutter } from '@codemirror/lint'
+import { EditorState } from '@codemirror/state'
+import { EditorView, lineNumbers } from '@codemirror/view'
+import { breakpointLines, breakpointsChanged, debug, setCurrentLine, stepcode } from '@stepcode/codemirror'
+import { profiles } from '@stepcode/profiles'
+
+const view = new EditorView({
+  state: EditorState.create({
+    doc: 'Proceso hola\n  Escribir "hola";\nFinProceso',
+    extensions: [
+      stepcode({ profile: profiles.es }),
+      debug(),
+      // the host's choices:
+      syntaxHighlighting(defaultHighlightStyle),
+      lintGutter(),
+      lineNumbers(),
+      EditorView.updateListener.of((update) => {
+        if (breakpointsChanged(update)) console.log(breakpointLines(update.state))
+      }),
+    ],
+  }),
+  parent: document.body,
+})
+
+// from a paused run:
+view.dispatch({ effects: setCurrentLine.of(2) })
+```
+
+## What `stepcode()` bundles
+
+One `LanguageSupport` per profile: the syntax tree (compiled by `stepcode`'s `compile` inside
+a Lezer parser, so highlighting, diagnostics and completion never disagree), lint, folding,
+indentation, block matching (`Si` ↔ `FinSi`), completion with block snippets, signature help,
+hover, `F12` go to definition, and `←` for a typed `<-`. Switch profiles by wrapping it in a `Compartment`.
+
+Every piece is also exported alone: `stepcodeLanguage`, `stepcodeLint`, `stepcodeCompletion`,
+`stepcodeSignatureHelp`, `stepcodeHover`, `stepcodeBlockMatching`, `arrowInput`,
+`stepcodeKeymap`.
+`compileResultAt(state)` hands back the `CompileResult` the tree was built from, `treeDataAt(state)`
+adds the offset maps the features use, and `stepcodeDiagnostics(state, options)` is the lint
+mapping without the linter, for a host's own Problems panel.
+
+Not included on purpose: a highlight style, the lint gutter, line numbers, history, the
+default keymap.
+
+## Debugging
+
+`debug()` (or `breakpoints()` and `currentLine()` separately) is pure editor state:
+
+- a breakpoint gutter — click to toggle; `breakpointLines(state)` reads the lines,
+  `setBreakpoints.of(lines)` / `toggleBreakpoint.of({ line })` change them,
+  `breakpointsChanged(update)` tells an update listener when to resend them;
+- a current-line marker — `setCurrentLine.of(line | null)` highlights the line, marks the
+  gutter and scrolls it into view; `currentLineOf(state)` reads it back.
+
+Markers follow their lines through edits and vanish when the line is deleted.
+
+## Styling
+
+The bundle ships a base theme, so the CSS class hooks are there to override: the breakpoint
+gutter (`.cm-stepcode-breakpoints`, `.cm-stepcode-breakpoint`), the current line
+(`.cm-stepcode-current-line`, `.cm-stepcode-current-line-marker`), the hover and signature
+tooltips (`.cm-stepcode-hover`, `.cm-stepcode-signature`, `.cm-stepcode-signature-active`),
+and the matching keyword pair (`.cm-matchingBracket`, `.cm-nonmatchingBracket`).
+
+## Strings
+
+Diagnostics render through `stepcode`'s catalogs; the few strings this package adds (symbol
+kinds, "declared on line", snippet placeholders) come from its own table, which covers `es` and
+`en` and falls back to `en`. `stepcode({ profile, locale })` defaults `locale` to the profile's.

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { Language, LanguageSupport } from "@codemirror/language";
+import { Command, EditorView, KeyBinding, ViewUpdate } from "@codemirror/view";
+import "@codemirror/autocomplete";
+import { ResolvedProfile } from "@stepcode/profiles";
+import { BuiltinCall, Call, CompileResult, Identifier } from "stepcode";
+import { NodeProp, NodeSet, Tree } from "@lezer/common";
+import { EditorState, Extension } from "@codemirror/state";
+import { Diagnostic } from "@codemirror/lint";
+//#region src/arrow.d.ts
+/**
+ * Spec §5.11: typing the second character of `<-` writes `←` instead, so the document keeps the
+ * spelling the profile prints while the keyboard keeps the one it can reach. Off for a profile
+ * that does not spell the arrow, or that assigns with `=`.
+ */
+declare function arrowInput(profile: ResolvedProfile): Extension;
+//#endregion
+//#region src/options.d.ts
+/** What every language feature needs: the profile the tree was built with and a locale. */
+interface StepcodeOptions {
+  readonly profile: ResolvedProfile;
+  readonly locale: string;
+}
+//#endregion
+//#region src/completion.d.ts
+/** The source, registered through the language's data so `autocompletion()` picks it up. */
+declare function stepcodeCompletion(options: StepcodeOptions): Extension;
+//#endregion
+//#region src/debug.d.ts
+declare const toggleBreakpoint: import("@codemirror/state").StateEffectType<{
+  readonly line: number;
+}>;
+declare const setBreakpoints: import("@codemirror/state").StateEffectType<readonly number[]>;
+declare const setCurrentLine: import("@codemirror/state").StateEffectType<number | null>;
+/**
+ * Renders standalone: `stepcodeBaseTheme` rides along so its markers are visible even without
+ * `stepcode()`. `EditorState` dedupes identical extension values by identity, so combining this
+ * with `stepcode()` still installs the theme once.
+ */
+declare function breakpoints(): Extension;
+/** Renders standalone; see `breakpoints()` on why `stepcodeBaseTheme` is included here too. */
+declare function currentLine(): Extension;
+declare function debug(): Extension;
+/** 1-based, ascending; empty without the extension. */
+declare function breakpointLines(state: EditorState): number[];
+/** True when the update changed the breakpoint set — the host's cue to resend it. */
+declare function breakpointsChanged(update: ViewUpdate): boolean;
+/** 1-based, or null. */
+declare function currentLineOf(state: EditorState): number | null;
+//#endregion
+//#region src/definition.d.ts
+declare const goToDefinition: Command;
+/** F12 only; a mouse gesture is the host's choice (spec §5.10). */
+declare const stepcodeKeymap: readonly KeyBinding[];
+//#endregion
+//#region src/hover.d.ts
+/** Spec §5.9. */
+declare function stepcodeHover(options: StepcodeOptions): Extension;
+//#endregion
+//#region src/lint.d.ts
+/** The tree's compile diagnostics as CodeMirror diagnostics; empty before the first parse. */
+declare function stepcodeDiagnostics(state: EditorState, options: StepcodeOptions): readonly Diagnostic[];
+/** Lint from the tree, re-run after every completed parse. */
+declare function stepcodeLint(options: StepcodeOptions): Extension;
+//#endregion
+//#region src/matching.d.ts
+/**
+ * Spec §5.5: the stock matcher. Keyword, parenthesis, and bracket pairs all come from the
+ * `closedBy` / `openedBy` props on the leaves (spec §4.2); the `brackets` text config stays as
+ * the fallback for text the tree does not type.
+ */
+declare function stepcodeBlockMatching(): Extension;
+//#endregion
+//#region src/tree.d.ts
+/** What rides on the top node of every tree (spec §4.3). */
+interface TreeData {
+  readonly result: CompileResult;
+  /** offset of an identifier leaf → its AST node, for hover, go to definition, signature help */
+  readonly identifiers: ReadonlyMap<number, Identifier>;
+  /** offset of a Call or BuiltinCall node → its AST node */
+  readonly calls: ReadonlyMap<number, Call | BuiltinCall>;
+}
+//#endregion
+//#region src/parser.d.ts
+/**
+ * One `Language` per profile object, cached: `stepcodeCompletion` registers through its data
+ * facet, so every extension built for a profile must see the same instance.
+ *
+ * The cache keys on object identity (a `WeakMap`), so a profile must not be mutated after it is
+ * first passed here — a later mutation would silently apply to the cached `Language` too.
+ */
+declare function stepcodeLanguage(profile: ResolvedProfile): Language;
+/** The data on the current tree, or `null` before a parse has produced one. */
+declare function treeDataAt(state: EditorState): TreeData | null;
+declare function compileResultAt(state: EditorState): CompileResult | null;
+//#endregion
+//#region src/signature.d.ts
+/** Spec §5.8: a tooltip field recomputed on selection, document and tree changes. */
+declare function stepcodeSignatureHelp(options: StepcodeOptions): Extension;
+//#endregion
+//#region src/stepcode.d.ts
+/**
+ * Spec §7: everything for one profile. Deliberately absent: a highlight style, the lint
+ * gutter, line numbers, history and the default keymap — those are the host's.
+ */
+declare function stepcode(options: {
+  profile: ResolvedProfile;
+  locale?: string;
+  /** Include the autocompletion extension (default true); the editor's setting turns it off. */
+  completion?: boolean;
+  /** Rewrite a typed `<-` as `←` (default true) when the profile spells the arrow. */
+  arrow?: boolean;
+}): LanguageSupport;
+//#endregion
+export { type StepcodeOptions, type TreeData, arrowInput, breakpointLines, breakpoints, breakpointsChanged, compileResultAt, currentLine, currentLineOf, debug, goToDefinition, setBreakpoints, setCurrentLine, stepcode, stepcodeBlockMatching, stepcodeCompletion, stepcodeDiagnostics, stepcodeHover, stepcodeKeymap, stepcodeLanguage, stepcodeLint, stepcodeSignatureHelp, toggleBreakpoint, treeDataAt };