joys 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f57014ffde6b631763ac91f57e7a54f240fb7aeade5b01f731445100281de46
-  data.tar.gz: 9c47f04cc7c091f4b37ea2b41d5fce522a296aaf07a832175a0c5a586b9f7dc4
+  metadata.gz: e61c772b1a54599aa640ae7185d7c555584569b42a828a622585fe1926c5c875
+  data.tar.gz: 3386e6f05c3bf96bda1b3c89ee060896a4bf6d652a81044729929cb32ef21fdd
 SHA512:
-  metadata.gz: 401097615b3d3d9b0415656b844a9df2527115b65bcce31df696d1599c18541dad4c2a21b7a89cc9c2a38df33fe24e1f88ffa39e92b2230376b1d8b054079b01
-  data.tar.gz: dfc1aac233bfcaf4a14ec3afa1253a7e13b77b95874b0938daaf801fd7757173ce5bc3c62fddb27c63fb7c6efa512d7cb566a6f66fd62f30ac71e87442f010b3
+  metadata.gz: 6b64267c0567828a6ef1ddf5682336f03e33e06a7e2b4ed1ef4fabf0712a835be9ab1f69c449dc6c8bfb172b1bcfb876f00bb9a3f424bf0a6d6537d67fe39e26
+  data.tar.gz: 307da8295d8df3b53cac60d55c3550c42e2b3926e9b5de5629011f814acc6bda73fd97f541fc95afe4f0b76ff16441e92e06f27f133533b102cce1d87b13f69c

data/CHANGELOG.md

@@ -12,3 +12,11 @@
 
 - Updated README
 - Added main joys.rb
+
+
+## [0.1.3] - 2025-09-29
+
+- Added configurable markup parser
+- Added Static Site Generator
+- Added Static Data Layer
+- Added CLI Utility

data/README.md

@@ -49,6 +49,9 @@ p { txt user_input }  # "<script>alert('xss')</script>" becomes safe text
 # raw outputs HTML (use with caution)
 div { raw markdown_to_html(content) }
 
+# raw shortcut is available for those who find it tedious
+div { _ markdown_to_html(content) }
+
 # Pass raw: true to any tag
 div(content, raw: true)  # content renders as HTML
 ```
@@ -243,66 +246,6 @@ Joys.define(:layout, :main) do
   }
 end
 ```
-
----
-
-## Rails Integration
-
-### Setup
-
-```ruby
-# config/initializers/joys.rb
-require 'joys/rails'
-```
-
-### File Structure
-
-```
-app/views/joys/
-├── layouts/
-│   └── application.rb
-├── comps/
-│   ├── navbar.rb
-│   └── user_card.rb
-└── pages/
-    ├── dashboard.rb
-    └── users_show.rb
-```
-
-### Rails Helpers Work Seamlessly
-
-Joys is fully compatible with Rails `ActiveSupport::SafeBuffer`, so you can use all Rails helpers seamlessly.
-
-```ruby
-Joys.define(:page, :users_edit) do
-  layout(:main) {
-    push(:main) {
-      # Rails form helpers just work
-      form_with(model: @user) do |f|
-        div(cs: "field") {
-          f.label(:name)
-          f.text_field(:name, class: "input")
-        }
-        f.submit("Save", class: "btn btn-primary")
-      end
-      # As do route helpers
-      a("Back", href: users_path, cs: "link")
-    }
-  }
-end
-```
-
-Rendering from controllers could not be more simple!
-
-```
-class UsersController < ApplicationController
-  def show
-    @user = User.find(params[:id])
-    render_joys :users_show # renders from #{Rails.root}/app/views/joys/users_show.rb
-  end
-end
-```
-
 ---
 
 ## Real-World Example
@@ -819,130 +762,358 @@ Joys is designed to stay out of your way. At its core, it leans functional — y
 The DSL is the same either way — Joys just adapts.
 
 
+---
+
+# Joys Rails Integration
+
+## Installation
+
+Add to your Rails app's initializer:
+
 ```ruby
-class BaseLayout
-  include Joys::Helpers
+require 'joys'
+```
 
-  def render(&block)
-    html {
-      head { title("My App") }
-      body { block.call }
-    }
+Auto-detects Rails and configures integration automatically.
+
+## How It Works
+
+- **Framework Detection**: Checks for `ActionController::Base` and `Rails` 
+- **Helper Injection**: Adds all `ActionView::Helpers` to `Joys::Render::Helpers`
+- **Context Injection**: Provides `request`, `params`, `current_user`, `session` in templates
+- **Controller Integration**: Adds `render_joy` method to all controllers
+
+## Directory Structure
+
+```
+app/views/joys/
+├── layouts/          # Auto-loaded at boot (production)
+├── components/       # Auto-loaded at boot (production) 
+└── pages/           # Loaded on-demand
+```
+
+## Configuration
+
+```ruby
+# Optional - defaults shown
+Joys::Config.env = "development"  # or Rails.env
+Joys::Config.pages = "app/views/joys/pages"
+Joys::Config.layouts = "app/views/joys/layouts"  
+Joys::Config.components = "app/views/joys/components"
+```
+
+## Controller Usage
+
+```ruby
+class HomeController < ApplicationController
+  def index
+    render_joy :index  # loads app/views/joys/pages/index.rb
+  end
+  
+  def show
+    render_joy "users/show", user: User.find(params[:id])
   end
 end
+```
 
-class Dashboard < BaseLayout
+## Page Templates
+
+### Functional Pattern
+
+```ruby
+# app/views/joys/pages/index.rb
+data = {title: "Home", nav: link_to("About", "/about")}.freeze
+
+Joys.html {
+  layout(:main) {
+    push(:title) { txt data[:title] }
+    push(:body) { _ data[:nav] }
+  }
+}
+```
+
+### Class Pattern
+
+```ruby
+# app/views/joys/pages/index.rb
+class IndexPage
+  def initialize
+    @data = {title: "Home"}.freeze
+  end
+  
   def render
-    super {
-      div(cs: "dashboard") {
-        h1("Dashboard")
-        p("Rendered through OOP inheritance.")
-        a("Logout", cs:"btn",href:"/logout")
+    data = @data
+    Joys.html {
+      layout(:main) {
+        push(:title) { txt data[:title] }
+        push(:body) { _ link_to("About", "/about") }
       }
     }
   end
 end
 
-puts Dashboard.new.render
-# => <html><head><title>My App</title></head><body><div class="dashboard"><h1>Dashboard</h1><p>Rendered through OOP inheritance.</p><a class="btn" href="/logout">Logout</a></div></body></html>
+IndexPage.new.render
 ```
 
-You can pick the style that fits your project, or even mix them.
+## Rails Helpers
 
----
-## 🧩 Bespoke Page Architecture: Content-Driven Flexibility
+All Rails helpers available directly:
 
-**Perfect for landing pages, marketing campaigns, and any layout requiring easy reorganization.**
+```ruby
+Joys.html {
+  layout(:main) {
+    push(:body) {
+      _ link_to("Home", root_path)
+      _ image_tag("logo.png", class: "w-8")
+      _ form_with model: Post.new do |f|
+        f.text_field :title
+      end
+    }
+  }
+}
+```
 
-Modular Page Architecture lets you build pages as Ruby modules with clean data separation, allowing rapid section reorganization without touching template code.
+## Context Access
 
-### The Pattern: Data + Methods + Flexible Assembly
+```ruby
+# Available in all templates
+request.referer
+params[:id] 
+current_user.name
+session[:user_id]
+```
+
+## Components
 
 ```ruby
-# pages/product_launch.rb
-module ProductLaunch
-  DATA = {
-    hero: {
-      title: "Revolutionary SaaS Platform", 
-      cta: "Start Free Trial"
-    },
-    features: {
-      items: [
-        { title: "Lightning Fast", desc: "10x faster" },
-        { title: "Secure", desc: "Bank-level security" }
-      ]
-    }
-  }.freeze
+# app/views/joys/components/card.rb
+Joys.define :comp, :card do |title|
+  styles { css ".card {padding:1rem;border:1px solid #ddd}" }
+  div(cs: "card") { h3 title }
+end
 
-  def self.render
-    Joys.define(:page, :product_launch) do
-      layout(:main) {
-        push(:main) {
-          raw hero(DATA[:hero])
-          raw features(DATA[:features])
-          
-          # Custom sections between data-driven ones
-          div(cs: "demo") {
-            h2("See It In Action")
-            comp(:demo_video)
-          }
-          
-          comp(:testimonials) # Reusable global component
-        }
-      }
-    end
-  end
+# Usage in templates
+comp :card, "Hello World"
+```
 
-  private
+## Page Components
 
-  def self.hero(data)
-    Joys.html {
-      styles { css ".hero { background: #667eea; padding: 4rem; }" }
-      # All css rendered and deduplicated within page scope
-      section(cs: "hero") {
-        h1(data[:title])
-        a(data[:cta], href: "/signup", cs: "btn")
-      }
+For page-specific components:
+
+```ruby
+page_comp(:hero) {
+  styles { css ".hero {text-align:center}" }
+  section(cs: "hero") { h1 "Welcome" }
+}
+```
+
+## Layouts
+
+```ruby
+# app/views/joys/layouts/main.rb
+Joys.define :layout, :main do
+  html {
+    head { 
+      title { pull(:title) }
+      pull_styles  # Auto-compiled CSS
     }
+    body { pull(:body) }
+  }
+end
+```
+
+## Raw HTML
+
+Use `_` for unescaped HTML:
+
+```ruby
+div {
+  _ "<strong>Bold</strong>"
+  _ link_to("Link", "/")
+  txt "Escaped text"  # Auto-escaped
+}
+```
+
+## Data Passing
+
+```ruby
+# Controller
+render_joy :show, user: current_user, posts: @posts
+
+# Template  
+user_name = @user.name
+post_count = @posts.count
+
+Joys.html {
+  layout(:main) {
+    push(:body) { h1 "Hello #{user_name}" }
+  }
+}
+```
+
+## Environment Behavior
+
+- **Development**: Templates reload on every request
+- **Production**: Layouts/components preloaded at boot, pages cached after first render
+
+---
+
+## Markup Processing in Joys
+
+Joys includes a powerful shorthand for processing markup content directly within your templates using the `?` suffix on any tag method.
+
+### Basic Usage
+
+Any tag method can be followed by `?` to process its content through a markup parser:
+
+```ruby
+# Process content with your configured markup parser
+div?("# Welcome to Joys") 
+# => <div><h1>Welcome to Joys</h1></div>
+
+p?("This is **bold** and *italic* text")
+# => <p>This is <strong>bold</strong> and <em>italic</em> text</p>
+
+article? do
+  h2?("## Getting Started")
+  p?("Learn how to use the `tag?` methods")
+end
+```
+
+### Configuration
+
+Configure your preferred markup parser globally:
+
+```ruby
+# Using Kramdown
+Joys::Config.markup_parser = ->(content) { 
+  Kramdown::Document.new(content).to_html 
+}
+
+# Using CommonMarker
+Joys::Config.markup_parser = ->(content) {
+  CommonMarker.render_html(content)
+}
+
+# Using any custom parser
+Joys::Config.markup_parser = ->(content) {
+  MyCustomParser.process(content)
+}
+```
+
+### 🎯 Recommended: Sparx Parser
+
+For the best developer experience, we recommend **[Sparx](https://github.com/activestylus/sparx)** - a modern markup language designed specifically for the Joys ecosystem:
+
+```ruby
+# Install: gem install sparx
+Joys::Config.markup_parser = ->(content) { 
+  Sparx.parse(content) 
+}
+```
+
+#### Why Sparx?
+
+Sparx eliminates the frustrations of traditional Markdown with:
+
+- **Consistent syntax** - No more `**bold**` vs `__bold__` confusion
+- **Perfect nesting** - Formatting works reliably in complex content
+- **Semantic HTML** - Clean, accessible output throughout
+- **URL references** - Define URLs once, use them everywhere
+- **Responsive images** - Built-in support for modern image requirements
+- **Academic citations** - Proper citation handling out of the box
+
+#### Sparx Examples
+
+```ruby
+# Clean, consistent formatting
+div? do
+  p?("*[Bold] and /[italic] with perfect */[nesting]https://example.com")
+  # => <p><strong>Bold</strong> and <em>italic</em> with perfect <strong><em><a href="https://example.com">nesting</a></em></strong></p>
+end
+
+# Responsive images with art direction
+div? do
+  p?("i[Hero]@cdn/hero.jpg 400w|hero@2x.jpg 800w")
+  # => Generates full <picture> element with responsive sources
+end
+
+# Complex content with semantic structure
+article? do
+  p?("+[Technical Details]{:Performance:100x faster parsing:Output:Semantic HTML5}")
+  # => Creates <details> with definition list inside
+end
+```
+
+### Comparison with Other Methods
+
+```ruby
+# Raw text (no processing)
+div("## This won't parse")
+# => <div>## This won't parse</div>
+
+# Raw HTML (dangerous with user content)
+div!("<h1>Raw HTML</h1>") 
+# => <div><h1>Raw HTML</h1></div>
+
+# Markup processing (recommended)
+div?("## This becomes H1")
+# => <div><h1>This becomes H1</h1></div>
+```
+
+### Advanced Usage
+
+#### Inline with Other Tags
+
+```ruby
+div(cs: "content") do
+  h1?("# Article Title")
+  div?(css: "prose") do
+    p?("First paragraph with *[bold] text")
+    blockquote?("> Important quote here")
+    ul?("- Item one\n- Item two\n- Item three")
   end
+end
+```
 
-  def self.features(data)
-    Joys.html {
-      section(cs: "features") {
-        data[:items].each { |item|
-          div {
-            h3(item[:title])
-            p(item[:desc])
-          }
-        }
-      }
-    }
+#### With Component Composition
+
+```ruby
+Joys.register(:comp, :blog_post) do |title:, content:|
+  article do
+    header do
+      h1(title)
+      time(Time.now.iso8601)
+    end
+    div?(cs: "content") { raw content }
   end
 end
+
+# Usage with Sparx content
+Joys.comp(:blog_post, 
+  title: "My Article",
+  content: Sparx.parse("## Introduction\n\nThis is the *[content]")
+)
 ```
 
-### Why This Pattern Works
+### Performance Notes
 
-**📊 Content Management Made Simple**
-- All page content in one DATA hash
-- Easy updates without touching templates
+- Markup parsing happens at **render time**, not registration time
+- Processing is **cached** along with the rest of your template
+- For maximum performance with user-generated content, consider pre-processing markup outside the template
 
-**🎯 Effortless Reorganization**  
-- Move sections by reordering method calls
-- Client requests become 30-second changes
+### Security
 
-**🧩 Best of All Worlds**
-- Data-driven sections for consistency
-- Custom HTML where needed  
-- Reusable global components
-- Page-specific anonymous components
+When processing user-generated content, ensure your markup parser is configured for safe mode:
 
-**⚡ Performance Benefits**
-- No global registry pollution
-- Page-scoped CSS compilation
-- Leverages existing Joys optimizations
+```ruby
+# With Sparx safe mode
+Joys::Config.markup_parser = ->(content) { 
+  Sparx.parse(content, safe: true) 
+}
+```
 
-This pattern transforms tedious page layout management into an agile, data-driven workflow that scales beautifully.
+The `?` suffix provides a clean, consistent way to integrate markup processing into your Joys templates while maintaining the framework's exceptional performance characteristics.
 
 ---