better readmes and apis

Author: rbbydotdev

editor/codemirror/README.md

@@ -1,78 +1,76 @@
 # @gnata-sqlite/codemirror
 
-CodeMirror 6 language support for [JSONata](https://jsonata.org) expressions — syntax highlighting, error diagnostics, autocomplete, and hover documentation, powered by a 380 KB WASM module (145 KB gzipped).
-
-## Features
-
-- **Syntax highlighting** — Lezer grammar with full JSONata 2.x coverage (works without WASM)
-- **Error diagnostics** — real-time squiggly underlines from the gnata parser
-- **Autocomplete** — context-aware: `$` triggers function completions with signatures, `.` triggers field completions from your data schema
-- **Hover documentation** — hover any `$function`, operator, keyword, or data field to see docs, signatures, and examples
+CodeMirror 6 language support for [JSONata](https://jsonata.org) — syntax highlighting, error diagnostics, autocomplete, and hover documentation.
 
 ## Install
 
 ```bash
 npm install @gnata-sqlite/codemirror
 ```
 
-You also need the WASM files served from your app:
-- `gnata-lsp.wasm` (380 KB, 145 KB gzipped)
-- `lsp-wasm_exec.js` (TinyGo runtime)
+Serve the WASM files from your app's public directory:
+- `gnata-lsp.wasm`
+- `lsp-wasm_exec.js`
+
+If you're using `@gnata-sqlite/react`, the WASM files are already included — run `npx @gnata-sqlite/react` to copy them into place.
 
 ## Quick Start
 
 ```ts
 import { EditorView, basicSetup } from "codemirror"
 import { initWasm, jsonataFull } from "@gnata-sqlite/codemirror"
+import "@gnata-sqlite/codemirror/styles.css"
 
-// 1. Load WASM (once, at startup)
 await initWasm("/gnata-lsp.wasm", "/lsp-wasm_exec.js")
 
-// 2. Create editor with full JSONata support
 new EditorView({
-  doc: '$sum(items.(price * quantity))',
-  extensions: [
-    basicSetup,
-    jsonataFull(),
-  ],
+  doc: '$sum(Account.Order.Product.(Price * Quantity))',
+  extensions: [basicSetup, jsonataFull()],
   parent: document.getElementById("editor")!,
 })
 ```
 
-That's it. You get syntax highlighting, diagnostics, autocomplete, and hover docs.
-
-## API
+That gives you syntax highlighting, diagnostics, autocomplete, and hover docs.
 
-### `initWasm(wasmUrl, execUrl)`
+## Data-Aware Completions
 
-Load the WASM module. Call once before creating editors. Returns a promise.
+Pass a schema to get field suggestions when typing after `.`:
 
 ```ts
-await initWasm("/assets/gnata-lsp.wasm", "/assets/lsp-wasm_exec.js")
-```
-
-### `jsonataFull(config?)`
-
-All-in-one extension: syntax highlighting + linting + autocomplete + hover.
+const schema = JSON.stringify({
+  fields: {
+    Account: {
+      type: "object",
+      fields: {
+        Order: { type: "array", fields: {
+          Product: { type: "array", fields: {
+            Price: { type: "number" },
+            Quantity: { type: "number" },
+          }}
+        }}
+      }
+    }
+  }
+})
 
-```ts
-jsonataFull()                          // basic — no schema
-jsonataFull({ schema: schemaString })  // with static schema
-jsonataFull({ schema: () => getSchema() })  // with dynamic schema
+jsonataFull({ schema })
+// or pass a getter for dynamic schemas:
+jsonataFull({ schema: () => currentSchema })
 ```
 
-The `schema` option enables field-aware autocomplete and hover. Pass a JSON string describing your data shape (see [Schema Format](#schema-format) below), or a getter function for dynamic schemas.
+Type `Account.Order.` and it suggests `Product` with type info. The `@gnata-sqlite/react` package exports a `buildSchema()` helper that generates this from sample JSON data.
 
-### Individual Extensions
+## Individual Extensions
 
-Use these for fine-grained control:
+`jsonataFull()` bundles everything. For fine-grained control, use the individual extensions:
 
 ```ts
 import {
   jsonata,           // syntax highlighting only (no WASM needed)
   jsonataLint,       // error diagnostics
   jsonataCompletion, // autocomplete
   jsonataHover,      // hover tooltips
+  jsonataLanguage,   // underlying language definition
 } from "@gnata-sqlite/codemirror"
 
 extensions: [
@@ -85,136 +83,33 @@ extensions: [
 ]
 ```
 
-### `jsonata()`
-
-Syntax highlighting only. Works without WASM — no `initWasm()` needed.
-
-## Schema Format
-
-The schema is a JSON string describing the shape of the input data. It enables field completions after `.` and type info on hover.
-
-```json
-{
-  "fields": {
-    "event": {
-      "type": "object",
-      "fields": {
-        "action": { "type": "string" },
-        "severity": { "type": "number" },
-        "user": { "type": "string" },
-        "metadata": {
-          "type": "object",
-          "fields": {
-            "ip": { "type": "string" },
-            "geo": { "type": "string" }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-You can build this from your data at runtime:
-
-```ts
-function buildSchema(data) {
-  if (!data || typeof data !== "object") return {}
-  if (Array.isArray(data)) {
-    return data.length > 0 ? buildSchema(data[0]) : {}
-  }
-  const fields = {}
-  for (const [key, val] of Object.entries(data)) {
-    const type = val === null ? "null"
-      : Array.isArray(val) ? "array"
-      : typeof val
-    const child = { type }
-    if (typeof val === "object" && val !== null) {
-      const nested = buildSchema(val)
-      if (nested.fields) child.fields = nested.fields
-    }
-    fields[key] = child
-  }
-  return { fields }
-}
-
-// Use it:
-const schema = JSON.stringify(buildSchema(myInputData))
-jsonataFull({ schema })
-```
+`jsonata()` works without WASM — use it for syntax highlighting only, no `initWasm()` needed.
 
 ## Styles
 
 Import the bundled stylesheet for Tokyo Night-themed tooltips, autocomplete, and lint styling:
 
 ```ts
-import '@gnata-sqlite/codemirror/styles.css'
+import "@gnata-sqlite/codemirror/styles.css"
 ```
 
 Includes dark mode (default) and light mode (when `<html>` lacks a `.dark` class). Override any class in your own CSS to customize.
 
-## Minimal Example
-
-```ts
-import { EditorView, basicSetup } from "codemirror"
-import { initWasm, jsonataFull } from "@gnata-sqlite/codemirror"
-
-await initWasm("/gnata-lsp.wasm", "/lsp-wasm_exec.js")
+## API Reference
 
-new EditorView({
-  doc: '$sum(Account.Order.Product.(Price * Quantity))',
-  extensions: [basicSetup, jsonataFull()],
-  parent: document.getElementById("editor")!,
-})
-```
+| Export | Description |
+|--------|-------------|
+| `initWasm(wasmUrl, execUrl)` | Load the WASM module. Call once at startup. Returns a promise. |
+| `jsonataFull(config?)` | All-in-one extension: highlighting + linting + autocomplete + hover. |
+| `jsonata()` | Syntax highlighting only. No WASM required. |
+| `jsonataLint()` | Error diagnostics extension. |
+| `jsonataCompletion(config?)` | Autocomplete source. Pass `{ schema }` for field completions. |
+| `jsonataHover(config?)` | Hover tooltip extension. Pass `{ schema }` for field type info. |
+| `jsonataLanguage` | Underlying Lezer language definition. |
+| `jsonataHighlighting` | Syntax highlighting style tags. |
 
-With a schema for field-aware autocomplete and hover:
+Schema config accepts `{ schema: string | (() => string) }`.
 
-```ts
-const schema = JSON.stringify({
-  fields: {
-    Account: {
-      type: "object",
-      fields: {
-        Order: { type: "array", fields: {
-          Product: { type: "array", fields: {
-            Price: { type: "number" },
-            Quantity: { type: "number" },
-          }}
-        }}
-      }
-    }
-  }
-})
-
-new EditorView({
-  doc: 'Account.Order.',
-  extensions: [basicSetup, jsonataFull({ schema })],
-  parent: document.getElementById("editor")!,
-})
-```
-
-## Architecture
-
-```
-┌─────────────────────────────┐     ┌───────────────────────────────┐
-│   Your App (browser)        │     │  gnata-lsp.wasm (145 KB)      │
-│                             │     │  TinyGo WASM module           │
-│  CodeMirror Editor          │────▶│                               │
-│  + @gnata-sqlite/codemirror │     │  _gnataDiagnostics(expr)      │
-│                             │◀────│  _gnataCompletions(...)       │
-│                             │     │  _gnataHover(expr, pos)       │
-└─────────────────────────────┘     └───────────────────────────────┘
-```
-
-The WASM module contains the gnata parser and a catalog of 89 built-in JSONata functions with full documentation. It runs entirely in the browser — no server calls needed.
-
-## Native LSP
-
-The same Go code also builds as a native LSP server for VS Code / Neovim:
-
-```bash
-go build -o gnata-lsp ./editor/
-```
+## License
 
-Supports `textDocument/didOpen`, `textDocument/didChange`, `textDocument/completion`, `textDocument/hover`, and diagnostics.
+MIT

playground/src/App.css

@@ -172,11 +172,18 @@ kbd { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; fo
 
 /* gnata mode wrapper */
 .gnata-mode-wrapper { display: flex; flex-direction: column; flex: 1; overflow: hidden; min-height: 0; }
-
-/* Ensure CodeMirror editors fill their containers in gnata mode */
 .gnata-mode-wrapper .cm-editor { height: 100%; }
 .gnata-mode-wrapper .cm-scroller { overflow: auto !important; }
 
+/* gnata expression bar */
+.expression-bar { display: flex; align-items: stretch; border-bottom: 1px solid var(--border); background: var(--surface); flex-shrink: 0; }
+.expression-bar-label { padding: 10px 16px; font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.8px; color: var(--muted); border-right: 1px solid var(--border); display: flex; align-items: center; min-width: 120px; }
+
+/* gnata panels */
+.gnata-panels { display: grid; grid-template-columns: 1fr 1fr; flex: 1; overflow: hidden; min-height: 0; }
+.gnata-panel { display: flex; flex-direction: column; overflow: hidden; }
+.gnata-panel + .gnata-panel { border-left: 1px solid var(--border); }
+
 @media (max-width: 768px) {
   .panels { grid-template-columns: 1fr; }
   .editor-panel { border-right: none; border-bottom: 1px solid var(--border); min-height: 200px; }