Improve JSR package metadata

packages/decodal-codemirror/src/format.ts

@@ -0,0 +1,84 @@
+/**
+ * Decodal source formatting helpers for CodeMirror integrations.
+ *
+ * The formatter is backed by WebAssembly generated from the internal Rust
+ * `decodal-language-tools` crate. Call {@link initDecodalFormatter} once before
+ * using {@link formatDecodal} or {@link formatDecodalCommand}.
+ *
+ * @module
+ */
+import type { EditorView } from 'npm:@codemirror/view@^6.43.6';
+import initLanguageTools, { formatSource } from '../wasm/decodal_language_tools.js';
+
+let initialized = false;
+
+/** Successful formatter result. */
+export interface FormatSuccess {
+  /** Indicates that formatting succeeded. */
+  ok: true;
+  /** The formatted Decodal source text. */
+  source: string;
+}
+
+/** Failed formatter result. */
+export interface FormatFailure {
+  /** Indicates that formatting failed. */
+  ok: false;
+  /** Human-readable formatter error. */
+  error: string;
+}
+
+/** Result returned by {@link formatDecodal}. */
+export type FormatResult = FormatSuccess | FormatFailure;
+
+/**
+ * Initialize the bundled Decodal formatter WebAssembly module.
+ *
+ * Bundlers such as Vite should pass the package wasm asset URL explicitly:
+ *
+ * ```ts
+ * import wasmUrl from 'decodal-codemirror/wasm/decodal_language_tools_bg.wasm?url';
+ * await initDecodalFormatter(wasmUrl);
+ * ```
+ *
+ * @param moduleOrPath - Optional WebAssembly module, bytes, response, URL, or
+ * request accepted by wasm-bindgen's generated initializer.
+ */
+export async function initDecodalFormatter(
+  moduleOrPath?: RequestInfo | URL | Response | BufferSource | WebAssembly.Module,
+): Promise<void> {
+  await initLanguageTools(moduleOrPath);
+  initialized = true;
+}
+
+/**
+ * Format a complete Decodal source document.
+ *
+ * @param source - Source text to format.
+ * @returns Either formatted source text or an error message.
+ */
+export function formatDecodal(source: string): FormatResult {
+  if (!initialized) {
+    return { ok: false, error: 'Decodal formatter is not initialized' };
+  }
+  return JSON.parse(formatSource(source)) as FormatResult;
+}
+
+/**
+ * CodeMirror command that formats the whole document in-place.
+ *
+ * @param view - The editor view whose document should be formatted.
+ * @returns `true` when the document was formatted, otherwise `false`.
+ */
+export function formatDecodalCommand(view: EditorView): boolean {
+  const result = formatDecodal(view.state.doc.toString());
+  if (!result.ok) return false;
+  view.dispatch({
+    changes: {
+      from: 0,
+      to: view.state.doc.length,
+      insert: result.source,
+    },
+  });
+  return true;
+}

packages/decodal-codemirror/src/mod.ts

@@ -1,3 +1,13 @@
+/**
+ * CodeMirror 6 language support for Decodal.
+ *
+ * This module exports the Decodal language extension, parser metadata, and the
+ * bundled highlight style used by the official Decodal playground. Add
+ * {@link decodal} to a CodeMirror extension set to enable highlighting,
+ * indentation, and folding for Decodal documents.
+ *
+ * @module
+ */
 import { HighlightStyle, LRLanguage, LanguageSupport, foldNodeProp, indentNodeProp, syntaxHighlighting } from 'npm:@codemirror/language@^6.12.4';
 import { styleTags, tags as t } from 'npm:@lezer/highlight@^1.2.3';
 import { parser } from './decodal-parser-jsr.js';
@@ -44,6 +54,7 @@ function foldDelimited(open: string, close: string) {
   };
 }
 
+/** Decodal LR language definition for CodeMirror 6. */
 export const decodalLanguage: LRLanguage = LRLanguage.define({
   parser: parserWithMetadata,
   languageData: {
@@ -52,6 +63,7 @@ export const decodalLanguage: LRLanguage = LRLanguage.define({
   },
 });
 
+/** Default Decodal highlight style used by the playground. */
 export const decodalHighlightStyle: HighlightStyle = HighlightStyle.define([
   { tag: t.keyword, color: '#93c5fd', fontWeight: '700' },
   { tag: t.variableName, color: 'inherit' },
@@ -64,10 +76,19 @@ export const decodalHighlightStyle: HighlightStyle = HighlightStyle.define([
   { tag: [t.brace, t.squareBracket, t.paren, t.punctuation], color: '#f9a8d4' },
 ]);
 
+/** Options for {@link decodal}. */
 export interface DecodalOptions {
+  /** Include the bundled {@link decodalHighlightStyle}. Defaults to `true`. */
   highlight?: boolean;
 }
 
+/**
+ * Create CodeMirror language support for Decodal.
+ *
+ * @param options - Optional language support options.
+ * @returns A CodeMirror extension bundle containing the Decodal language and,
+ * unless disabled, the default highlight style.
+ */
 export function decodal(options: DecodalOptions = {}): LanguageSupport {
   const { highlight = true } = options;
   return new LanguageSupport(