rhales 0.3.0 → 0.5.3

data/demo/rhales-roda-demo/README.md

@@ -0,0 +1,376 @@
+# Rhales Roda Demo
+
+This demo application showcases the power of Rhales RSFC (Ruby Single File Components) templates integrated with a Roda web application using Rodauth for authentication.
+
+## Features Demonstrated
+
+- **RSFC Templates**: Single file components with `<data>`, `<template>`, `<schema>`, and `<logic>` sections
+- **Schema Validation**: Runtime validation of hydration data against Zod schemas
+- **Client-Side Hydration**: Secure data injection with CSP nonce support
+- **Authentication Integration**: Rodauth with custom Rhales adapters
+- **Dynamic Content**: Posts management with CRUD operations
+- **Handlebars Syntax**: Conditionals, iteration, and partials
+- **API Integration**: Client-side fetching with hydrated configuration
+
+## Prerequisites
+
+Before starting, ensure you have:
+- Ruby 3.0 or higher
+- Bundler gem installed (`gem install bundler`)
+- SQLite3 installed on your system
+- Node.js and pnpm (for schema generation)
+
+## Step-by-Step Setup Instructions
+
+### Step 1: Navigate to the demo directory
+
+From the root of the rhales gem repository:
+```bash
+cd demo/rhales-roda-demo
+```
+
+### Step 2: Install Ruby dependencies
+
+```bash
+bundle install
+```
+
+If you encounter errors:
+```bash
+# Update bundler
+gem install bundler
+
+# Try again
+bundle install
+```
+
+### Step 3: Install Node.js dependencies (for schema generation)
+
+```bash
+pnpm install
+```
+
+If you don't have pnpm installed:
+```bash
+npm install -g pnpm
+pnpm install
+```
+
+### Step 4: Generate JSON Schemas from templates
+
+```bash
+bundle exec rake rhales:schema:generate
+```
+
+This will:
+- Parse all `.rue` templates with `<schema>` sections
+- Execute Zod schema code to generate JSON Schemas
+- Save generated schemas to `public/schemas/`
+
+Expected output:
+```
+Schema Generation
+============================================================
+Templates: ./templates
+Output: ./public/schemas
+Zod: (using pnpm exec tsx)
+
+Found 2 schema section(s):
+  - login (js-zod)
+  - dashboard (js-zod)
+
+Generating JSON Schemas...
+✓ Generated schema for: login
+✓ Generated schema for: dashboard
+
+Results:
+------------------------------------------------------------
+✓ Successfully generated 2 schema(s)
+✓ Output directory: /path/to/demo/rhales-roda-demo/public/schemas
+```
+
+You can verify the generated schemas:
+```bash
+ls -la public/schemas/
+cat public/schemas/login.json | jq .
+```
+
+### Step 5: Start the web server
+
+```bash
+bundle exec rackup
+```
+
+Expected output:
+```
+Puma starting in single mode...
+* Puma version: 6.4.2 (ruby 3.0.0-p0) ("The Eagle of Durango")
+*  Min threads: 0
+*  Max threads: 5
+*  Environment: development
+*          PID: 12345
+* Listening on http://127.0.0.1:9292
+* Listening on http://[::1]:9292
+Use Ctrl-C to stop
+```
+
+### Step 6: Open your browser
+
+Visit: http://localhost:9292
+
+You should see the Rhales Demo homepage with feature cards.
+
+## Testing the Demo
+
+### Quick Test with Demo Account
+
+1. Click **"Login"** in the top navigation
+2. Enter credentials:
+   - Email: `demo@example.com`
+   - Password: `demo123`
+3. Click **"Login"** button
+4. You should see a dashboard with:
+   - Welcome message with the user's name
+   - Stats showing Total Posts, Published, and Drafts
+   - List of sample posts
+
+### Create Your Own Account
+
+1. From the homepage, click **"Register"**
+2. Fill out the form:
+   - Full Name: `Test User` (or your name)
+   - Email: `test@example.com` (any email works)
+   - Password: `testpass` (min 6 characters)
+   - Confirm Password: `testpass`
+3. Click **"Create Account"**
+4. You'll be automatically logged in and redirected to an empty dashboard
+
+### Test Post Management
+
+1. Click **"New Post"** button on the dashboard
+2. Fill out the form:
+   - Title: `My First Post`
+   - Content: `This is a test post using Rhales RSFC templates!`
+   - Status: `Published`
+3. Click **"Create Post"**
+4. You should see:
+   - Success message: "Post created successfully!"
+   - Your post in the dashboard list
+5. Try editing the post:
+   - Click **"Edit"** on your post
+   - Change the title or content
+   - Click **"Update Post"**
+6. Try deleting:
+   - Click **"Delete"**
+   - Confirm the deletion
+   - Post should disappear with success message
+
+### Test Client-Side Hydration
+
+1. Click **"Profile"** in the navigation
+2. You'll see your account information
+3. Click **"Fetch Stats"** button
+4. Watch as it makes an API call and displays JSON response
+5. Open browser console (F12) to see hydration logs
+
+### Logout
+
+Click **"Logout"** in the navigation to end your session.
+
+## Development Mode
+
+For automatic server restarts when files change:
+
+```bash
+bundle exec rerun rackup
+```
+
+Now when you edit any `.rb` or `.rue` file, the server will restart automatically.
+
+## Schema Generation and Validation
+
+### Generating Schemas
+
+Rhales uses Zod schemas defined in `.rue` templates to generate JSON Schemas for runtime validation:
+
+```bash
+# Generate all schemas
+bundle exec rake rhales:schema:generate
+
+# Custom paths
+bundle exec rake rhales:schema:generate \
+  TEMPLATES_DIR=./templates \
+  OUTPUT_DIR=./public/schemas
+
+# View statistics
+bundle exec rake rhales:schema:stats
+
+# Validate existing schemas
+bundle exec rake rhales:schema:validate
+```
+
+### Schema Sections in Templates
+
+Templates with `<schema>` sections define the shape of data they expect:
+
+```html
+<schema lang="js-zod" window="appData">
+const schema = z.object({
+  user: z.object({
+    name: z.string(),
+    email: z.string().email(),
+  }),
+  posts: z.array(z.object({
+    id: z.number(),
+    title: z.string(),
+  })),
+});
+</schema>
+```
+
+### Runtime Validation
+
+When schema validation is enabled (see `app.rb`), the middleware will:
+- Extract hydration data from HTML responses
+- Validate against the generated JSON Schema
+- In development: Fail loudly with detailed error messages
+- In production: Log warnings but continue serving
+
+### Directory Structure
+
+```
+demo/rhales-roda-demo/
+├── templates/           # Source .rue files
+│   ├── login.rue       # With <schema> section
+│   └── dashboard.rue   # With <schema> section
+├── public/
+│   └── schemas/        # Generated JSON Schemas (gitignored)
+│       ├── login.json
+│       └── dashboard.json
+└── app.rb              # Schema validation middleware config
+```
+
+## Understanding the Code
+
+### Key Files to Explore
+
+1. **app.rb** - Main application file
+   - Shows Rhales configuration
+   - Custom auth/session adapters
+   - Route definitions
+   - `rhales_render` helper method
+
+2. **templates/layouts/main.rue** - Layout template
+   - Shows conditional navigation
+   - CSP nonce usage in styles
+   - Flash message handling
+
+3. **templates/home.rue** - Homepage
+   - Data hydration with `window` attribute
+   - Feature iteration
+   - Client-side JavaScript integration
+
+4. **templates/dashboard/index.rue** - Dashboard
+   - Uses partials (`{{> post_item}}`)
+   - Conditional rendering
+   - Stats display
+
+## Troubleshooting
+
+### Port 9292 already in use
+
+```bash
+# Use a different port
+bundle exec rackup -p 9293
+
+# Or find and kill the process using port 9292
+lsof -i :9292
+kill -9 <PID>
+```
+
+### Bundle install fails
+
+```bash
+# Check Ruby version
+ruby -v  # Should be 3.0 or higher
+
+# Update RubyGems
+gem update --system
+
+# Try installing problematic gems individually
+gem install sqlite3 -v '2.0.0'
+gem install rack-session -v '2.0.0'
+```
+
+### Rack::Session errors
+
+If you see "uninitialized constant Rack::Session" or "invalid secret" errors:
+```bash
+bundle install  # Make sure rack-session and rackup gems are installed
+bundle binstub rack  # Fix rackup binstub conflicts if needed
+bundle exec rackup  # Try again
+```
+
+### SQLite3 LoadError
+
+Install SQLite3 for your system:
+
+```bash
+# macOS
+brew install sqlite3
+
+# Ubuntu/Debian
+sudo apt-get install sqlite3 libsqlite3-dev
+
+# Fedora/RHEL
+sudo dnf install sqlite sqlite-devel
+```
+
+Then reinstall the gem:
+```bash
+gem uninstall sqlite3
+bundle install
+```
+
+### Template not found
+
+Verify template files exist:
+```bash
+find templates -name "*.rue" | sort
+```
+
+Should show:
+```
+templates/auth/login.rue
+templates/auth/register.rue
+templates/dashboard/index.rue
+templates/dashboard/post_form.rue
+templates/dashboard/profile.rue
+templates/home.rue
+templates/layouts/main.rue
+templates/partials/post_item.rue
+```
+
+### No CSS styling
+
+The demo includes inline CSS in the layout. If styles aren't loading:
+1. Check browser console for CSP errors
+2. Verify the `{{runtime.nonce}}` is being replaced in templates
+3. Try hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
+
+## Next Steps
+
+1. Explore the `.rue` template files to understand RSFC structure
+2. Modify templates and see live changes
+3. Add new routes and templates
+4. Integrate Rhales into your own Ruby applications
+
+## Architecture Overview
+
+- **Roda**: Lightweight Ruby web framework
+- **Rodauth**: Full-featured authentication
+- **Sequel**: Database toolkit with models
+- **SQLite**: Zero-config database
+- **Rhales**: RSFC template engine with hydration
+
+This demo shows how Rhales integrates seamlessly with existing Ruby tools while adding powerful component-based templating.

data/demo/rhales-roda-demo/RODA-TEMPLATE-ENGINES.md

@@ -0,0 +1,192 @@
+# Custom Template Engines in Roda
+
+Roda's render plugin uses Tilt to support multiple template engines. You can use any template engine that Tilt supports, or integrate custom template engines in several ways.
+
+## Using Template Engines Already Supported by Tilt
+
+Tilt supports 25+ template engines out of the box. To use a different engine, specify it in the `:engine` option:
+
+```ruby
+plugin :render, engine: 'haml'
+plugin :render, engine: 'slim'
+plugin :render, engine: 'liquid'
+```
+
+You can also specify the engine per template:
+
+```ruby
+render('template', engine: 'haml')
+view('template', engine: 'slim')
+```
+
+## Adding New Template Engines to Tilt
+
+As of 2025, Tilt is actively maintained by Jeremy Evans but no longer accepts new community template engine integrations in the main gem. If you want to add support for a template engine not currently supported by Tilt, you should:
+
+1. Create a separate gem that provides Tilt integration for your template engine
+2. Have the template engine itself ship with Tilt integration
+
+To register a new template engine with Tilt:
+
+```ruby
+# In your gem or application
+require 'tilt'
+
+class MyTemplateEngine < Tilt::Template
+  def prepare
+    # Parse/compile template during template creation
+  end
+
+  def evaluate(scope, locals, &block)
+    # Render template with given scope and locals
+  end
+end
+
+# Register with Tilt
+Tilt.register MyTemplateEngine, 'myengine'
+
+# Or for multiple extensions
+Tilt.register MyTemplateEngine, 'myengine', 'mytempl'
+```
+
+Then use it in Roda:
+
+```ruby
+plugin :render, engine: 'myengine'
+render('template') # renders template.myengine
+```
+
+## Layouts
+
+ In Roda, you can specify layouts and create defaults through the render plugin configuration:
+
+  Specifying a Layout File
+```ruby
+  # Set a specific layout file
+  plugin :render, layout: 'my_layout'
+
+  # Or specify per-render
+  render('template', layout: 'specific_layout')
+```
+
+  Creating Default Layout
+
+  Roda automatically looks for layout.erb (or .engine extension) in your views directory. To create a default layout:
+
+```html
+  # views/layout.erb
+  <!DOCTYPE html>
+  <html>
+  <head>
+    <title>My App</title>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+  </html>
+```
+
+  Layout Configuration Options
+
+```ruby
+  plugin :render,
+    layout: 'layout',           # Default layout file
+    layout_opts: {engine: 'erb'}, # Layout-specific options
+    views: 'views'              # Views directory
+```
+
+  The layout file receives the rendered template content via yield and can access the same instance variables and locals as your templates.
+
+
+## Using Custom Template Classes Directly
+
+For maximum control, you can bypass Tilt entirely and provide your own template class using the `:template_class` option:
+
+```ruby
+class MyCustomTemplate
+  def initialize(file, line, options={}, &block)
+    @template_string = block ? block.call : File.read(file)
+    # Custom initialization
+  end
+
+  def render(scope, locals={}, &block)
+    # Custom rendering logic
+    # Return rendered string
+  end
+end
+
+# Use globally
+plugin :render, template_class: MyCustomTemplate
+
+# Or per-template
+render('template', template_class: MyCustomTemplate)
+```
+
+## Engine-Specific Options
+
+Configure options for specific template engines using `:engine_opts`:
+
+```ruby
+plugin :render,
+  engine_opts: {
+    'erb' => {default_encoding: 'UTF-8'},
+    'haml' => {format: :html5, escape_html: true},
+    'slim' => {pretty: true}
+  }
+```
+
+## Example: Adding Mustache Support
+
+Here's a complete example of adding Mustache template support:
+
+```ruby
+require 'mustache'
+require 'tilt'
+
+class TiltMustacheTemplate < Tilt::Template
+  def prepare
+    @engine = Mustache.new
+    @engine.template = data
+  end
+
+  def evaluate(scope, locals, &block)
+    @engine.render(locals)
+  end
+end
+
+Tilt.register TiltMustacheTemplate, 'mustache'
+
+# In your Roda app
+plugin :render, engine: 'mustache'
+
+route do |r|
+  r.get do
+    view('template', locals: {name: 'World'}) # renders template.mustache
+  end
+end
+```
+
+## Tilt Maintenance Status
+
+**Current Status**: Tilt is actively maintained by Jeremy Evans (also the maintainer of Roda) as of 2025.
+
+**Recent Activity**:
+- Version 2.6.0 released January 13, 2025
+- Version 2.5.0 released December 20, 2024
+- 0 open issues and pull requests (excellent maintenance)
+
+**Policy on New Engines**: The Tilt team no longer accepts new community-maintained template integrations into the main gem. New template engines should implement their own Tilt compatibility in separate gems.
+
+**Supported Engines**: Tilt currently supports 25+ template engines including ERB, Erubi, Haml, Slim, Markdown engines (CommonMarker, Kramdown, Redcarpet), Sass/SCSS, CoffeeScript, TypeScript, Liquid, Builder, Nokogiri, and many more.
+
+## Best Practices
+
+1. **Use existing engines**: Check if Tilt already supports your desired template engine before creating a custom integration.
+
+2. **Separate gems**: If you need a new template engine, create a separate gem with Tilt integration rather than modifying Tilt directly.
+
+3. **Performance**: Use the `:template_class` option for maximum performance if you don't need Tilt's generic interface.
+
+4. **Caching**: Custom template classes should support Roda's caching mechanisms for best performance.
+
+5. **Error handling**: Ensure your custom template engines provide proper error messages with filename and line number information.

data/demo/rhales-roda-demo/Rakefile

@@ -0,0 +1,49 @@
+# Rakefile for rhales-roda-demo
+
+# Load Rhales rake tasks for schema generation
+# Note: In a real project, these would be loaded from the gem
+# For this demo, we load from the local gem directory
+begin
+  # Try loading from local gem development directory
+  rake_tasks = File.expand_path('../../lib/tasks/rhales_schema.rake', __dir__)
+  load rake_tasks if File.exist?(rake_tasks)
+rescue LoadError
+  # Fallback: load from installed gem
+  spec = Gem::Specification.find_by_name('rhales')
+  load "#{spec.gem_dir}/lib/tasks/rhales_schema.rake"
+end
+
+desc 'Run CI integration test (replicates GitHub Actions workflow)'
+task :ci_test do
+  puts "Installing demo dependencies..."
+  system('bundle install') || (puts "Failed to install dependencies" && exit(1))
+
+  puts "Starting demo server..."
+  server_pid = spawn('bundle exec rackup -p 9393')
+  puts "Server PID: #{server_pid}"
+
+  begin
+    # Wait for server to start
+    sleep 1
+
+    # Test the server (replicates: curl -f http://localhost:9393/ || exit 1)
+    puts "Testing demo server..."
+    success = system('curl -f http://localhost:9393/')
+    puts "Curl exit status: #{$?.exitstatus}"
+
+    if success
+      puts "✓ Demo integration test passed"
+    else
+      puts "✗ Demo integration test failed"
+      exit 1
+    end
+  ensure
+    # Clean up (replicates: pkill -f rackup || true)
+    if server_pid
+      Process.kill('TERM', server_pid) rescue nil
+      Process.wait(server_pid) rescue nil
+    end
+  end
+end
+
+task default: :ci_test