npm package: @jotx-labs/language
Description: jotx language support - Syntax highlighting and diagnostics for VS Code and Monaco
Latest version: 2.4.253

# @jotx-labs/language

Platform-agnostic language support for jotx files (`.jot`, `.meet`).

Provides syntax highlighting and diagnostics for **both VS Code and Monaco Editor** (web).

---

## Features

✅ **Syntax Highlighting** (TextMate grammar - works in VS Code & Monaco)
✅ **Real-time Diagnostics** (validation with red squiggles)
✅ **Platform-agnostic** (core logic works anywhere)
✅ **VS Code integration** (ready to use)
✅ **Monaco integration** (for web apps)

---

## Installation

```bash
npm install @jotx-labs/language
```

---

## Usage

### For VS Code Extension

```typescript
import * as vscode from 'vscode'
import { setupJotxLanguageForVSCode } from '@jotx-labs/language'

export function activate(context: vscode.ExtensionContext) {
  // Setup jotx language support (syntax + diagnostics)
  const languageProvider = setupJotxLanguageForVSCode(vscode, context)
  
  // Language support is now active!
  // Users will see:
  // - Syntax highlighting
  // - Real-time validation with red squiggles
  // - Error messages on hover
}
```

### For Monaco Editor (Web)

```typescript
import * as monaco from 'monaco-editor'
import { setupJotxLanguageForMonaco } from '@jotx-labs/language'

// Setup jotx language
const languageProvider = setupJotxLanguageForMonaco(monaco)

// Create editor
const editor = monaco.editor.create(document.getElementById('editor'), {
  value: 'hdef jot my_doc\n  title "Hello"',
  language: 'jotx',
  theme: 'vs-dark'
})

// Validate on change
editor.onDidChangeModelContent(() => {
  const model = editor.getModel()
  if (model) {
    const text = model.getValue()
    const markers = languageProvider.validate(text)
    monaco.editor.setModelMarkers(model, 'jotx', markers)
  }
})
```

### Platform-agnostic Validation

```typescript
import { DiagnosticProvider } from '@jotx-labs/language'

const provider = new DiagnosticProvider()

const text = `
hdef jot my_doc
  title "Test"
  
  def heading1 block_1
    text """Hello World"""
`

const result = provider.validate(text)

console.log('Valid:', result.isValid)
console.log('Errors:', result.diagnostics)
```

---

## Architecture

```
@jotx/language
├── Diagnostics (Core)          Platform-agnostic validation
├── VS Code Integration         Diagnostic provider for VS Code
├── Monaco Integration          Language provider for Monaco
└── Grammar (TextMate)          Syntax highlighting (both)
```

**Benefits:**
- ✅ Write validation logic once, use everywhere
- ✅ Same syntax highlighting in VS Code and web
- ✅ Easy to add support for other editors (Vim, Emacs, etc.)

---

## API

### DiagnosticProvider (Core)

```typescript
class DiagnosticProvider {
  validate(text: string): DiagnosticResult
  isValid(text: string): boolean
  getErrors(text: string): JotxDiagnostic[]
  getWarnings(text: string): JotxDiagnostic[]
}
```

### VSCodeLanguageProvider

```typescript
class VSCodeLanguageProvider {
  register(context: ExtensionContext): void
  validateDocument(document: TextDocument): Diagnostic[]
  clear(): void
  dispose(): void
}
```

### MonacoLanguageProvider

```typescript
class MonacoLanguageProvider {
  register(): void
  validate(text: string): any[]  // Monaco markers
}
```

---

## Supported Block Types

Syntax highlighting for all 21 jotx block types:

**Document Types:** jot, meeting, tasklist, journal
**Text Blocks:** heading1-3, paragraph, quote
**Code/Media:** code, math, image
**Containers:** callout, toggle
**Lists:** list, checklist
**Data:** table, properties
**Separators:** divider, link, attach
**Interactive:** mermaid, chart, datetime, linkCard
**Custom:** custom

---

## Diagnostics

Real-time validation catches:

❌ **Errors:**
- Invalid block types
- Missing required properties
- Syntax errors
- Parse failures

⚠️ **Warnings:**
- Deprecated syntax
- Unused properties

ℹ️ **Info:**
- Style suggestions
- Formatting hints

---

## Development

```bash
# Build
npm run build

# Test
npm test

# Clean
npm run clean
```

---

## License

MIT