sparx 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 205c14fff56e350a5da9ded41bf7ed7a6deb90a03cf511f51647e59c1febda56
+  data.tar.gz: be9ed8508d53945c5610cd3d8aa4c79bb86305307676eec136284686c8da67ea
+SHA512:
+  metadata.gz: c995d71f8f0c758c53c9eb0309fa3c693858e601a66078f99d9537df50604ca35a445491b3c486434df4dd6ef1c88ff505de85d0291a3bee6a2f8a0a770f68e2
+  data.tar.gz: c7188911afe4c0b8cbb1aa50919a885cc1a8382c8a06781c81da6d132a547df3d8fcf0889e4797c30d5a98f5a4f12830d4bdc7c90c5278d52e3e766d5b836f46

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Steven Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,446 @@
+# Sparx - Markup That Sparks Joy
+
+**Markdown was revolutionary in 2004. It's 2025. Time for the next evolution.**
+
+Born from the same "spark joy" philosophy as the **[Joys](https://github.com/activestylus/joys)** view engine, Sparx eliminates the daily frustrations that developers face, thanks to its clean syntax, semantic HTML and zero compromise on ergonomics and features.
+
+---
+
+## The Problem With Markdown
+
+After 20 years, we're still fighting the same battles:
+- `**bold**` vs `__bold__` vs `*italic*` confusion
+- Broken nesting in complex formatting
+- HTML soup whenever you need anything semantic
+- Copying URLs everywhere like it's 1999
+- Zero support for modern responsive images
+- Academic citations? Good luck.
+
+**Sparx** solves every single one of these problems.
+
+---
+
+## Quick Taste: Before & After
+
+### The Old Way (Markdown)
+```markdown
+**Bold** and *italic* with [broken **nesting**](https://example.com).
+
+![Image](https://cdn.example.com/very/long/path/image.jpg)
+
+<details>
+<summary>Advanced Content</summary>
+More HTML soup when you need structure.
+</details>
+```
+
+### The Sparx Way
+```sparx
+*[Bold] and /[italic] with perfect */[nesting]https://example.com.
+
+i[Image]@cdn/image.jpg
+
++[Advanced Content]{
+  Clean structure without HTML soup.
+}
+
+@cdn: https://cdn.example.com/very/long/path/
+```
+
+Same result. Half the characters. Semantic HTML throughout. URLs defined once.
+
+---
+
+## Installation & Usage
+
+### With Joys Framework
+```ruby
+gem install sparx
+
+class ArticlePage < Joys::Component
+  def initialize(content)
+    @html = Sparx.parse(content)
+  end
+
+  def template
+    article do
+      unsafe_raw @html  # Already sanitized and semantic
+    end
+  end
+end
+```
+
+### Standalone
+```ruby
+gem install sparx
+require 'sparx'
+
+html = Sparx.parse(your_content)
+```
+
+---
+
+## Core Philosophy: Consistency Over Convention
+
+### Logical, Predictable Formatting
+
+**Input:**
+```
+*[bold] /[italic] -[deleted] `code`
+*/[bold italic] -*[bold deleted] 
+```
+
+**Output:**
+```html
+<strong>bold</strong> <em>italic</em> <del>deleted</del> <code>code</code>
+<strong><em>bold italic</em></strong> <del><strong>bold deleted</strong></del>
+```
+
+Every formatting element follows the same pattern: `symbol[content]`. No exceptions. No edge cases. Perfect nesting every time.
+
+### Links That Don't Break Your Flow
+
+**Input:**
+```
+[GitHub]https://github.com
+[Docs|Complete documentation]@docs^
+[Call us]tel:+1-555-0199
+
+@docs: https://sparx.dev/docs
+```
+
+**Output:**
+```html
+<a href="https://github.com">GitHub</a>
+<a href="https://sparx.dev/docs" title="Complete documentation" target="_blank">Docs</a>
+<a href="tel:+1-555-0199">Call us</a>
+```
+
+Links, tooltips, targets, and protocols all work the same way. Define URLs once with `@references`, use them everywhere.
+
+---
+
+## Where Sparx Shines: Complex Content
+
+### Responsive Images (Finally!)
+
+**Basic responsive images:**
+```
+i[Hero]hero.jpg 400w|hero@2x.jpg 800w|hero@3x.jpg 1200w
+```
+
+**Art direction with format fallbacks:**
+```
+src[>800px]desktop.{webp,jpg}
+src[>400px]tablet.{webp,jpg}
+i[Hero]mobile.jpg
+```
+
+**Output:**
+```html
+<picture>
+  <source srcset="desktop.webp" type="image/webp" media="(min-width: 800px)">
+  <source srcset="desktop.jpg" type="image/jpeg" media="(min-width: 800px)">
+  <source srcset="tablet.webp" type="image/webp" media="(min-width: 400px)">
+  <source srcset="tablet.jpg" type="image/jpeg" media="(min-width: 400px)">
+  <img src="mobile.jpg" alt="Hero">
+</picture>
+```
+
+One input. Perfect responsive HTML5. Try doing this in Markdown!
+
+### Semantic Containers
+
+You can create linkable sections with very simple syntax:
+
+`$[dom-id] { fully parseable content }`
+
+**Input:**
+```
+$[hero]{
+  # Welcome to */[the future]@site
+
+  >{
+    Finally, markup that doesn't make me want to scream.
+    - Every developer who tries Sparx
+  }
+
+  .warning{
+    This will change how you think about markup.
+  }
+
+  +[Technical Details]{
+    :Performance: 100x faster parsing than traditional regex approaches
+    :Output: Clean, semantic HTML5 throughout
+    :DRY: URL references eliminate repetition
+  }
+}
+
+@site: https://sparx.dev
+```
+
+**Output:**
+```html
+<section id="hero">
+<h1>Welcome to <strong><em><a href="https://sparx.dev">the future</a></em></strong></h1>
+<blockquote>
+<p>Finally, markup that doesn't make me want to scream.</p>
+<p>- Every developer who tries Sparx</p>
+</blockquote>
+<div class="warning">
+<p>This will change how you think about markup.</p>
+</div>
+<details>
+<summary>Technical Details</summary>
+<dl>
+<dt>Performance</dt><dd>100x faster parsing than traditional regex approaches</dd>
+<dt>Output</dt><dd>Clean, semantic HTML5 throughout</dd>
+<dt>DRY</dt><dd>URL references eliminate repetition</dd>
+</dl>
+</details>
+</section>
+```
+
+Every element generates proper semantic HTML. Your accessibility audits will love you.
+
+Links to these sections can then be easily created:
+
+`[Go To Hero]#hero`
+
+---
+
+## Real-World Comparison
+
+### Documentation Page: Markdown vs Sparx
+
+**Markdown approach:**
+```markdown
+## API Authentication
+
+> **Warning:** Never commit tokens to version control.
+
+See our [security guide](https://docs.example.com/security) and 
+[API docs](https://docs.example.com/api).
+
+<details>
+<summary>Troubleshooting</summary>
+
+**Token Issues:**
+- Check for whitespace
+- Verify token type
+
+**Expired Tokens:**
+- Tokens expire in 30 days
+- Generate new ones [here](https://app.example.com/tokens)
+
+</details>
+
+References:
+1. [OAuth 2.0](https://tools.ietf.org/html/rfc6749) - Official spec
+2. [JWT Guide](https://jwt.io/introduction/) - Token format
+```
+
+**Sparx approach:**
+```
+## API Authentication
+
+.warning{
+  **Never commit tokens to version control.**
+}
+
+See our [security guide]@docs/security and [API docs]@docs/api.
+
++[Troubleshooting]{
+  :Token Issues:{
+    - Check for whitespace  
+    - Verify token type
+  }
+  :Expired Tokens:{
+    - Tokens expire in 30 days
+    - Generate new ones [here]@app/tokens
+  }
+}
+
+See the [OAuth 2.0 spec]:1 and [JWT guide]:2 for details.
+
+@docs: https://docs.example.com
+@app: https://app.example.com
+
+1[OAuth 2.0]https://tools.ietf.org/html/rfc6749 "Official spec"
+2[JWT Guide]https://jwt.io/introduction/ "Token format"
+```
+
+**Result:** 16% shorter, semantic HTML throughout, DRY URLs, automatic citations.
+
+---
+
+## Advanced Features
+
+### Academic Citations
+```
+Research shows[significant performance gains]:1 in modern applications.
+
+1[Performance Study]https://journal.example.com "Peer-reviewed research"
+```
+
+Automatic numbering, proper linking, and citation sections.
+
+### Complex Lists
+```
+- Simple item
+-{
+  ## Complex item with full formatting
+  
+  Complete *[markup support], [links]@docs, and more.
+  
+  >{
+    Even blockquotes work perfectly inside lists.
+  }
+}
+- Back to simple
+```
+
+Try nesting a blockquote inside a Markdown list item. I'll wait.
+
+### Protocol Links
+```
+[Email us]mailto:hello@example.com
+[Call support]tel:+1-555-0199
+[Text us]sms:+1-555-0199
+[Video chat]facetime:user@example.com
+[Open in VS Code]vscode://file/path/to/file
+```
+
+Built-in support for `tel:`, `mailto:`, `sms:`, `facetime:`, `skype:`, `whatsapp:`, `zoom:`, `spotify:`, `vscode:`, and `geo:` protocols.
+
+---
+
+## Security: Safe Mode
+
+Processing user-generated content? Sparx's safe mode protects against XSS while preserving all formatting functionality.
+
+```ruby
+# Safe mode ON - for user content
+html = Sparx.parse(user_content, safe: true)
+
+# Safe mode OFF - for trusted content  
+html = Sparx.parse(trusted_content)
+```
+
+Automatically escapes HTML tags, blocks dangerous protocols (`javascript:`, `data:`), and sanitizes attributes while preserving code blocks exactly as written.
+
+---
+## Performance
+
+Sparx prioritizes developer experience and semantic output over raw speed. While pure Markdown parsers like Redcarpet are faster for basic formatting, Sparx delivers significantly more functionality:
+
+### Performance Benchmarks
+
+Sparx balances speed with advanced functionality. While pure Markdown parsers prioritize raw throughput, Sparx generates semantic HTML5 with features impossible in traditional markup languages.
+
+### Benchmark Results
+
+*Tested on Ruby 3.3.5 (arm64-darwin23) across three document types*
+
+#### Blog Post (746 characters)
+
+| Parser | Speed (ops/sec) | Relative | Memory |
+|--------|-----------------|----------|--------|
+| Redcarpet | 257,851 | **1.0x** | <1 KB |
+| **Sparx** | **4,576** | **56x slower** | **64 KB** |
+| Kramdown | 2,207 | 117x slower | 3,520 KB |
+| CommonMarker | 478 | 539x slower | 2,608 KB |
+
+#### Technical Documentation (2,367 characters)
+
+| Parser | Speed (ops/sec) | Relative | Memory |
+|--------|-----------------|----------|--------|
+| Redcarpet | 79,432 | **1.0x** | <1 KB|
+| **Sparx** | **1,450** | **55x slower** | **<1 KB** |
+| Kramdown | 840 | 95x slower | <1 KB |
+| CommonMarker | 147 | 541x slower | 384 KB |
+
+#### Novel Chapter (27,465 characters)
+
+| Parser | Speed (ops/sec) | Relative | Memory |
+|--------|-----------------|----------|--------|
+| Redcarpet | 12,738 | **1.0x** | 48 KB |
+| CommonMarker | 898 | 14x slower | 432 KB |
+| **Sparx** | **457** | **28x slower** | **16 KB** |
+| Kramdown | 290 | 44x slower | 16 KB |
+
+### What These Numbers Mean
+
+#### The Speed Tradeoff
+- **Redcarpet wins on pure speed** but only handles basic Markdown
+- **Sparx is 2x faster than Kramdown** while delivering dramatically more features
+- **Performance scales well** with document size (28x slower vs 56x slower)
+
+### Feature Comparison
+
+| Feature | Redcarpet | Kramdown | CommonMarker | **Sparx** |
+|---------|-----------|----------|--------------|---------------|
+| Basic Markdown | ✅ | ✅ | ✅ | ✅ |
+| Semantic HTML5 | ❌ | Limited | ❌ | **✅** |
+| URL References | ❌ | ❌ | ❌ | **✅** |
+| Responsive Images | ❌ | ❌ | ❌ | **✅** |
+| Citations | ❌ | ❌ | ❌ | **✅** |
+| Complex Containers | ❌ | Limited | ❌ | **✅** |
+| Definition Lists | ❌ | ✅ | ❌ | **✅** |
+| Perfect Nesting | ❌ | ❌ | ❌ | **✅** |
+
+### Real-World Performance
+
+For typical use cases, Sparx's parsing time is negligible:
+
+- **Blog post** (746 chars): **0.22ms** to parse
+- **Documentation** (2.3K chars): **0.69ms** to parse  
+- **Long content** (27K chars): **2.19ms** to parse
+
+The development time saved by consistent syntax and semantic output far outweighs the microseconds spent parsing.
+
+## Bottom Line
+
+**Choose based on your needs:**
+
+- **Need raw speed only?** Redcarpet is unbeatable for basic Markdown
+- **Need features + reasonable speed?** Sparx delivers 2x better performance than Kramdown with 10x more functionality
+- **Building semantic, accessible content?** Sparx is the only option that generates proper HTML5 throughout
+
+*Performance measured in iterations per second. Higher is better. Memory usage measured as RSS delta during parsing.*
+
+Conclusion: For most real-world use cases, the parsing time is negligible compared to the development time saved by cleaner syntax and semantic output.
+
+---
+
+## When to Use Sparx
+
+**Perfect for:**
+- Technical documentation requiring semantic structure
+- Content sites where HTML5 semantics matter
+- Academic writing with proper citations
+- Any project where Markdown feels limiting
+- Teams tired of mixed HTML/Markdown soup
+
+**Stick with Markdown when:**
+- Writing simple blog posts without complex structure
+- Your toolchain is deeply invested in Markdown  
+- Your team values familiarity over power
+
+---
+
+## The Bottom Line
+
+Markdown taught us that writing shouldn't require thinking about HTML. Sparx teaches us that **developers** shouldn't need to compromise on semantic markup quality.
+
+It's 2025. Your markup language should be as sophisticated as your code.
+
+**Does your current markup spark joy?**
+
+```ruby
+gem install sparx
+```
+
+---
+
+*Sparx is part of the [Joys](https://github.com/activestylus/joys) ecosystem - Ruby tools that spark joy for developers.*

data/bin/sparx

@@ -0,0 +1,133 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/sparx'
+require 'listen'
+
+# --- Configuration ---
+WATCH_INTERVAL = 0.5 # Debounce interval for listen
+
+# --- Helper Methods ---
+
+def display_help
+  puts <<~HELP
+    Sparx CLI - Markup that sparks joy ✨
+
+    Usage:
+      sparx convert <input.sx> [output.html] [--safe]
+      sparx watch <directory>
+      sparx init
+      sparx version
+      sparx help
+
+    Options:
+      --safe, -s  Enable safe mode for user-generated content
+
+    Examples:
+      sparx convert blog.sx                      # Output to stdout
+      sparx convert blog.sx blog.html            # Output to file
+      sparx convert comments.sx --safe           # Safe mode for user content
+      sparx watch docs/                          # Auto-convert files in docs/
+  HELP
+end
+
+def process_file(file, output_file, safe_mode)
+  begin
+    content = File.read(file)
+    html = Sparx.parse(content, safe: safe_mode)
+
+    if output_file
+      File.write(output_file, html)
+      puts "✅ Converted #{File.basename(file)} -> #{File.basename(output_file)}"
+    else
+      # Output to stdout only if a single file is being processed in non-watch mode
+      puts html
+    end
+  rescue StandardError => e
+    puts "❌ Error processing #{file}: #{e.message}"
+    exit 1 unless output_file # Exit if in single-convert mode
+  end
+end
+
+# --- Main Logic ---
+
+command = ARGV[0] || 'help'
+options = ARGV[1..-1] || []
+
+# Parse common options
+safe_mode = options.include?('--safe') || options.include?('-s')
+options.delete('--safe')
+options.delete('-s')
+
+case command
+when 'convert'
+  input_file = options[0]
+  output_file = options[1]
+
+  unless input_file && File.exist?(input_file)
+    puts "File not found: #{input_file}"
+    exit 1
+  end
+
+  process_file(input_file, output_file, safe_mode)
+
+when 'watch'
+  dir = options[0]
+  
+  unless dir && File.directory?(dir)
+    puts "Directory not found or specified: #{dir}"
+    exit 1
+  end
+  
+  puts "✨ Sparx Watch Mode: Watching #{dir} for changes..."
+  puts "   (Press Ctrl+C to stop)"
+  
+  # Set up the listener
+  listener = Listen.to(dir, only: /\.sx\z/i, latency: WATCH_INTERVAL) do |modified, added, removed|
+    
+    # Process modified and added files
+    (modified + added).each do |file_path|
+      # Generate output path (e.g., input/doc.sx -> output/doc.html)
+      output_path = file_path.sub(/\.sx\z/i, '.html') 
+      process_file(file_path, output_path, safe_mode)
+    end
+    
+    # Handle removed files (optional, but good practice)
+    removed.each do |file_path|
+      puts "🗑️ File removed: #{File.basename(file_path)}"
+      # You could add logic here to delete the corresponding HTML file
+    end
+  end
+  
+  listener.start
+  sleep # Keep the main thread alive until Ctrl+C is pressed
+
+when 'init'
+  sample_content = <<~SPARKDOWN
+    # Welcome to Sparx
+
+    This is a */[sample document] to get you started.
+
+    i[Sparx Logo]https://placehold.co/400x200/EEE/31343C?text=Sparx
+
+    +[Quick Start]{
+      - Install: \`gem install sparx\`
+      - Convert: \`sparx convert sample.sx\`
+      - Learn: https://sparx.dev/docs
+    }
+  SPARKDOWN
+
+  File.write('sample.sx', sample_content)
+  puts "Created sample.sx - try: sparx convert sample.sx"
+
+when 'version'
+  # Assuming Sparx::VERSION is defined in your main library file
+  puts "Sparx #{Sparx::VERSION}" 
+
+when 'help', '--help', '-h'
+  display_help
+
+else
+  puts "Unknown command: #{command}"
+  display_help
+  exit 1
+end

data/editors/sublime-text/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "Sparx",
+  "details": "https://github.com/activestylus/sparx",
+  "description": "Sparx syntax highlighting for Sublime Text",
+  "author": "yourname",
+  "releases": [
+    {
+      "sublime_text": ">=3000",
+      "tags": true
+    }
+  ],
+  "version": "1.0.0"
+}

data/editors/vscode/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "sparx",
+  "displayName": "Sparx Syntax Highlighting",
+  "description": "Syntax highlighting for Sparx markup language",
+  "version": "1.0.0",
+  "publisher": "sparx",
+  "engines": {
+    "vscode": "^1.60.0"
+  },
+  "categories": ["Programming Languages"],
+  "contributes": {
+    "languages": [{
+      "id": "sparx",
+      "aliases": ["Sparx", "sparx"],
+      "extensions": [".hug", ".sparx"],
+      "configuration": "./language-configuration.json"
+    }],
+    "grammars": [{
+      "language": "sparx",
+      "scopeName": "source.sparx",
+      "path": "../../syntaxes/sparx.tmLanguage.json"
+    }],
+    "themes": [{
+      "label": "Sparx Dark",
+      "uiTheme": "vs-dark",
+      "path": "../../themes/sparx-dark-color-theme.json"
+    }]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/activestylus/sparx"
+  }
+}