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: $id="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 <%= %>
$id	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:

<Define:UserCard>
  <div class="user-card" $id="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:

{
  "[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:

<% 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:

{
  "[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:

# 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