rspade_system/node_modules/@jqhtml/vscode-extension/README.md

# JQHTML VS Code Extension

Syntax highlighting and language support for JQHTML template files.

## Features

### Syntax Highlighting

Full syntax highlighting for all JQHTML constructs:

- **Component Definitions**: `<Define:ComponentName>`
- **Template Expressions**: `<%= expression %>`
- **Control Flow**: `<% if (condition) { %> ... <% } %>`
- **Slots**: `<#slotname>` with let:prop support
- **Data Bindings**: `:property="value"`
- **Event Handlers**: `@click="handler"`
- **Special Attributes**: `$sid="name"`, `$property="value"`
- **Components**: `<MyComponent />`
- **Comments**: `<%-- comment --%>`

### Language Configuration

- **Auto-closing pairs**: Automatically close tags, brackets, and quotes
- **Bracket matching**: Highlight matching brackets and tags
- **Code folding**: Fold component definitions
- **Smart indentation**: Handles control flow
- **Comment toggling**: Use standard VS Code shortcuts to toggle comments

### Code Snippets

Quick snippets for common patterns:

| Prefix | Description |
|--------|-------------|
| `define` | Component definition |
| `definecomp` | Component with structure |
| `if` | If statement |
| `ifelse` | If-else |
| `for` | For loop |
| `exp` | Expression `<%= %>` |
| `$sid` | Scoped ID attribute |
| `:prop` | Property binding |
| `@event` | Event handler |
| `slot` | Named slot |
| `slotprop` | Slot with props |
| `comment` | Comment block |

## Installation

### From Marketplace (when published)

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "JQHTML"
4. Click Install

### From Source (Development)

1. Clone the JQHTML repository
2. Navigate to `packages/vscode-extension`
3. Run `npm install`
4. Run `npm run compile`
5. Copy the folder to VS Code extensions directory:
   - Windows: `%USERPROFILE%\.vscode\extensions`
   - macOS/Linux: `~/.vscode/extensions`
6. Restart VS Code

### Using .vsix Package

1. Package the extension: `vsce package`
2. In VS Code: Extensions → ... → Install from VSIX
3. Select the generated .vsix file

## Usage

The extension automatically activates for `.jqhtml` files. Features include:

### Syntax Highlighting

All JQHTML syntax is highlighted with semantic colors:

```jqhtml
<Define:UserCard>
  <div class="user-card" $sid="card">
    <h2><%= this.data.name %></h2>

    <% if (this.data.isAdmin) { %>
      <span class="admin">Admin</span>
    <% } %>

    <button @click="handleClick">Click Me</button>

    <% for (const skill of this.data.skills) { %>
      <div class="skill"><%= skill %></div>
    <% } %>
  </div>
</Define:UserCard>
```

### IntelliSense

Basic HTML tag and attribute completion is provided through VS Code's built-in HTML support.

### Code Folding

Component definitions can be folded at the `<Define:>` level:

```
▼ <Define:MyComponent>
  ...
  </Define:MyComponent>
```

### Formatting Support

The extension respects VS Code's formatting settings.

## Configuration

The extension sets these defaults for JQHTML files:

```json
{
  "[jqhtml]": {
    "editor.wordWrap": "on",
    "editor.quickSuggestions": {
      "other": true,
      "comments": false,
      "strings": true
    }
  }
}
```

You can override these in your VS Code settings.

## Theme Support

The extension uses standard TextMate scopes and works with all VS Code themes. For best results, use a theme with good HTML/JavaScript support.

### Scope Reference

- `entity.name.class.component.jqhtml` - Component names
- `entity.name.tag.slot.jqhtml` - Slot names (header, row, footer, etc.)
- `keyword.control.slot.jqhtml` - Slot prefix `#` symbol
- `keyword.control.flow.jqhtml` - Control flow keywords (if, for, etc.)
- `punctuation.definition.attribute.special.jqhtml` - `$` prefix
- `punctuation.definition.attribute.binding.jqhtml` - `:` prefix
- `punctuation.definition.attribute.event.jqhtml` - `@` prefix

## Known Issues

### Bracket Matching Errors with Split Control Flow

When using control flow split across multiple `<% %>` blocks, VS Code may show bracket matching errors:

```jqhtml
<% if (condition) { %>
  <div>Content</div>
<% } else if (otherCondition) { %>  ⚠️ VS Code shows bracket error here
  <div>Other content</div>
<% } %>
```

**Why this happens:** VS Code's bracket matcher can't track bracket state across separate template blocks. It sees a closing `}` without a matching opening `{` in the same block.

**Solution:** The extension automatically disables bracket colorization for `.jqhtml` files:

```json
{
  "[jqhtml]": {
    "editor.bracketPairColorization.enabled": false,
    "editor.guides.bracketPairs": false
  }
}
```

These visual errors don't affect functionality.

### Other Known Issues

- Complex nested template expressions may not highlight perfectly
- Some edge cases in mixed HTML/JavaScript contexts

## Contributing

Contributions are welcome! The extension source is in the JQHTML repository under `packages/vscode-extension`.

### Development

1. Clone the repository
2. Open in VS Code
3. Run `npm install`
4. Press F5 to launch a new VS Code window with the extension
5. Open a `.jqhtml` file to test

### Testing

Create test files in `test-files/` to verify syntax highlighting:

```bash
# Run automated tests
npm test

# Manual testing
# 1. Launch extension (F5)
# 2. Open test files
# 3. Verify highlighting
```

## License

MIT License - See LICENSE file in the JQHTML repository

## Changelog

### 2.0.0
- Initial release
- Full JQHTML v2 syntax support
- Brace-style control flow
- Slot syntax with let:prop
- Data binding and event handlers
- Component highlighting
- Code snippets