funicular 0.0.1 → 0.1.0

data/docs/routing-and-navigation.md

@@ -0,0 +1,427 @@
+# Routing and Navigation
+
+This guide covers Funicular's built-in client-side routing and the Rails-style `link_to` helper for navigation.
+
+## Table of Contents
+
+- [Router Setup](#router-setup)
+- [Defining Routes](#defining-routes)
+- [URL Parameters](#url-parameters)
+- [Named Routes and URL Helpers](#named-routes-and-url-helpers)
+- [Programmatic Navigation](#programmatic-navigation)
+- [link_to Helper](#link_to-helper)
+- [Route Constraints](#route-constraints)
+- [Best Practices](#best-practices)
+
+## Router Setup
+
+Initialize the router when starting your application:
+
+```ruby
+Funicular.start(container: 'app') do |router|
+  router.get('/login', to: LoginComponent, as: 'login')
+  router.get('/dashboard', to: DashboardComponent, as: 'dashboard')
+  router.get('/settings', to: SettingsComponent, as: 'settings')
+
+  router.set_default('/login')  # Redirect / to /login
+end
+```
+
+The router:
+- Uses the History API for SPA navigation
+- Listens to browser back/forward buttons
+- Automatically mounts/unmounts components on route changes
+
+## Defining Routes
+
+### Basic Routes
+
+```ruby
+router.get('/about', to: AboutComponent, as: 'about')
+router.get('/contact', to: ContactComponent, as: 'contact')
+```
+
+### HTTP Method Routes
+
+While Funicular is client-side, you can define method-specific routes for semantic clarity:
+
+```ruby
+router.get('/posts', to: PostListComponent, as: 'posts')
+router.post('/posts', to: CreatePostComponent, as: 'create_post')
+router.delete('/posts/:id', to: DeletePostComponent, as: 'delete_post')
+```
+
+**Note**: These routes are for client-side organization. For server communication, use the `link_to` helper with `method:` option (see below).
+
+## URL Parameters
+
+Define dynamic routes with `:param` syntax:
+
+```ruby
+router.get('/users/:id', to: UserProfileComponent, as: 'user')
+router.get('/posts/:post_id/comments/:comment_id', to: CommentDetailComponent, as: 'comment')
+```
+
+Access parameters in your component via `props`:
+
+```ruby
+class UserProfileComponent < Funicular::Component
+  def component_mounted
+    user_id = props[:id]  # From /users/:id
+    User.find(user_id) do |user|
+      patch(user: user)
+    end
+  end
+
+  def render
+    div do
+      h1 { "User Profile: #{props[:id]}" }
+      if state.user
+        p { state.user.name }
+      end
+    end
+  end
+end
+```
+
+## Route Constraints
+
+You can add regular expression constraints to URL parameters. When a constraint is specified, the route only matches if the parameter value matches the pattern. This is useful for distinguishing routes that share the same structure but accept different parameter formats.
+
+```ruby
+Funicular.start(container: 'app') do |router|
+  # Only matches when :id is numeric
+  router.get('/users/:id', to: UserProfileComponent, as: 'user', constraints: { id: /\d+/ })
+
+  # Only matches when :channel_id is numeric
+  router.get('/chat/:channel_id', to: ChatComponent, as: 'chat_channel', constraints: { channel_id: /\d+/ })
+
+  # Multiple parameters can each have constraints
+  router.get('/posts/:year/:month', to: ArchiveComponent, as: 'archive', constraints: { year: /\d{4}/, month: /\d{1,2}/ })
+
+  # No constraint - matches any string
+  router.get('/pages/:slug', to: PageComponent, as: 'page')
+end
+```
+
+The `constraints` option takes a Hash mapping parameter names (as Symbols) to Regexp objects. If a segment does not match its constraint, the router skips that route and continues to the next candidate.
+
+**Note**: Constraints use `Regexp#match?`, which is backed by JavaScript's `RegExp` engine in PicoRuby.wasm.
+
+## Named Routes and URL Helpers
+
+The `as:` parameter generates URL helper methods:
+
+```ruby
+router.get('/users/:id', to: UserProfileComponent, as: 'user')
+router.get('/posts/:id/edit', to: EditPostComponent, as: 'edit_post')
+router.get('/settings', to: SettingsComponent, as: 'settings')
+```
+
+Use helpers via `RouteHelpers` module:
+
+```ruby
+include Funicular::RouteHelpers
+
+user_path(123)           # => "/users/123"
+edit_post_path(456)      # => "/posts/456/edit"
+settings_path            # => "/settings"
+```
+
+### With Model Objects
+
+Helpers work with objects that respond to `#id`:
+
+```ruby
+user = User.new(id: 123, name: "Alice")
+user_path(user)  # => "/users/123"
+
+post = Post.new(id: 456, title: "Hello")
+edit_post_path(post)  # => "/posts/456/edit"
+```
+
+### In Components
+
+```ruby
+class UserCard < Funicular::Component
+  include Funicular::RouteHelpers
+
+  def render
+    div do
+      h3 { props[:user].name }
+      link_to user_path(props[:user]), navigate: true do
+        span { "View Profile" }
+      end
+    end
+  end
+end
+```
+
+## Programmatic Navigation
+
+Navigate imperatively using the router instance:
+
+```ruby
+class LoginComponent < Funicular::Component
+  def handle_login
+    User.authenticate(state.credentials) do |user, error|
+      if user
+        # Navigate to dashboard on success
+        Funicular.router.navigate('/dashboard')
+      else
+        patch(error: error)
+      end
+    end
+  end
+
+  def render
+    button(onclick: -> { handle_login }) { "Login" }
+  end
+end
+```
+
+### Getting Current Path
+
+```ruby
+Funicular.router.current_path  # => "/users/123"
+```
+
+## link_to Helper
+
+The `link_to` helper provides Rails-style navigation and actions. It intelligently chooses between navigation (`<a>` tags) and actions (`<div>` tags) based on context.
+
+### Navigation Links
+
+Use `navigate: true` for client-side page transitions:
+
+```ruby
+class Navigation < Funicular::Component
+  include Funicular::RouteHelpers
+
+  def render
+    nav do
+      link_to dashboard_path, navigate: true, class: "nav-link" do
+        span { "Dashboard" }
+      end
+
+      link_to settings_path, navigate: true, class: "nav-link" do
+        span { "Settings" }
+      end
+    end
+  end
+end
+```
+
+**Behavior**:
+- Generates `<a href="/path">` tag
+- Normal click: SPA navigation via History API (no page reload)
+- Right-click → "Open in New Tab": Opens URL in new tab
+- Browser features work: link preview, copy link, etc.
+
+### Action Links
+
+For server actions (create, update, delete), omit `navigate:`:
+
+```ruby
+class MessageItem < Funicular::Component
+  include Funicular::RouteHelpers
+
+  def render
+    div do
+      p { props[:message].content }
+
+      # DELETE request to server
+      link_to message_path(props[:message]), method: :delete, class: "delete-btn" do
+        span { "Delete" }
+      end
+    end
+  end
+end
+```
+
+**Behavior**:
+- Generates `<div>` tag (not `<a>`)
+- Sends HTTP request via Fetch API
+- Supports all HTTP methods: `:get`, `:post`, `:put`, `:patch`, `:delete`
+
+### Why Different Elements?
+
+| Type | Element | Use Case | Browser Features |
+|------|---------|----------|------------------|
+| **Navigation** | `<a href>` | Page transitions | ✅ Right-click menu, new tab |
+| **Action** | `<div>` | Server operations | ❌ Not a link (semantically correct) |
+
+### Custom Response Handling
+
+Override `handle_link_response` to customize action response handling:
+
+```ruby
+class ChatComponent < Funicular::Component
+  def handle_link_response(response, path, method)
+    if response.error?
+      puts "Action failed: #{response.error_message}"
+      patch(error: response.error_message)
+    else
+      puts "Action succeeded!"
+      # Update state based on response
+      if method == :delete
+        # Remove deleted item from state
+        patch(messages: state.messages.reject { |m| m.id == response.data[:id] })
+      end
+    end
+  end
+
+  def render
+    state.messages.map do |message|
+      link_to message_path(message), method: :delete, class: "text-red-600" do
+        span { "Delete" }
+      end
+    end
+  end
+end
+```
+
+### Styling Links
+
+```ruby
+class Navigation < Funicular::Component
+  include Funicular::RouteHelpers
+
+  styles do
+    nav_link base: "px-4 py-2 text-gray-700 hover:bg-gray-100 rounded transition-colors",
+             active: "bg-blue-100 text-blue-700 font-semibold"
+  end
+
+  def render
+    nav(class: "flex gap-2") do
+      link_to dashboard_path,
+              navigate: true,
+              class: s.nav_link(is_current_path?(dashboard_path)) do
+        span { "Dashboard" }
+      end
+
+      link_to settings_path,
+              navigate: true,
+              class: s.nav_link(is_current_path?(settings_path)) do
+        span { "Settings" }
+      end
+    end
+  end
+
+  def is_current_path?(path)
+    Funicular.router.current_path == path
+  end
+end
+```
+
+## Best Practices
+
+### 1. Use Named Routes
+
+```ruby
+# ✅ Good: Named routes
+router.get('/users/:id', to: UserProfileComponent, as: 'user')
+link_to user_path(user), navigate: true
+
+# ❌ Avoid: Hard-coded paths
+link_to "/users/#{user.id}", navigate: true
+```
+
+### 2. Choose Correct Element Type
+
+```ruby
+# ✅ Navigation: use <a> tag
+link_to settings_path, navigate: true do
+  span { "Settings" }
+end
+
+# ✅ Server action: use <div> tag
+link_to post_path(post), method: :delete do
+  span { "Delete Post" }
+end
+
+# ❌ Avoid: Using navigate: true for server actions
+link_to post_path(post), method: :delete, navigate: true  # Wrong!
+```
+
+### 3. Include RouteHelpers
+
+```ruby
+# ✅ Include in components that use routing
+class MyComponent < Funicular::Component
+  include Funicular::RouteHelpers
+
+  def render
+    link_to user_path(user), navigate: true
+  end
+end
+```
+
+### 4. Handle Loading States
+
+```ruby
+def handle_navigation
+  patch(is_loading: true)
+
+  # Load data, then navigate
+  User.find(id) do |user|
+    patch(is_loading: false, user: user)
+    Funicular.router.navigate(user_path(user))
+  end
+end
+```
+
+### 5. Validate Before Navigation
+
+```ruby
+def handle_next_step
+  if state.form_valid?
+    Funicular.router.navigate('/step-2')
+  else
+    patch(errors: validate_form)
+  end
+end
+```
+
+## Advanced: Route Guards
+
+Implement route guards by checking conditions in `component_mounted`:
+
+```ruby
+class DashboardComponent < Funicular::Component
+  def component_mounted
+    # Redirect to login if not authenticated
+    unless Session.authenticated?
+      Funicular.router.navigate('/login')
+      return
+    end
+
+    # Load dashboard data
+    load_suspense_data
+  end
+end
+```
+
+## Integration with Rails Routes
+
+If using Funicular with Rails, you can mirror Rails routes on the client:
+
+```ruby
+# Rails routes.rb
+Rails.application.routes.draw do
+  get '/dashboard', to: 'pages#dashboard'
+  resources :users
+  resources :posts do
+    resources :comments
+  end
+end
+
+# Funicular router
+Funicular.start(container: 'app') do |router|
+  router.get('/dashboard', to: DashboardComponent, as: 'dashboard')
+  router.get('/users/:id', to: UserProfileComponent, as: 'user')
+  router.get('/posts/:post_id/comments/:comment_id', to: CommentDetailComponent, as: 'comment')
+end
+```
+
+This allows you to use the same path helpers on both client and server.

data/docs/styling.md

@@ -0,0 +1,285 @@
+# CSS-in-Ruby with Styles DSL
+
+Funicular provides a powerful CSS-in-Ruby DSL that keeps your styles organized and scoped within each component.
+
+## Table of Contents
+
+- [Basic Usage](#basic-usage)
+- [Conditional Styles](#conditional-styles)
+- [Variant Styles](#variant-styles)
+- [Combining Styles](#combining-styles)
+- [Best Practices](#best-practices)
+
+## Basic Usage
+
+Define styles using the `styles` block at the top of your component:
+
+```ruby
+class LoginComponent < Funicular::Component
+  styles do
+    container "min-h-screen flex items-center justify-center bg-gradient-to-br from-blue-500 to-purple-600"
+    card "bg-white p-8 rounded-lg shadow-2xl w-96"
+    title "text-3xl font-bold text-center mb-8 text-gray-800"
+    input "w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+  end
+
+  def render
+    div(class: s.container) do
+      div(class: s.card) do
+        h1(class: s.title) { "Welcome" }
+        input(class: s.input, type: "text", placeholder: "Username")
+      end
+    end
+  end
+end
+```
+
+Access styles via the `s` helper in your render method.
+
+## Conditional Styles
+
+For styles that toggle based on state (like active/inactive), use the `active:` key:
+
+```ruby
+class ChannelList < Funicular::Component
+  styles do
+    channel_item base: "p-4 hover:bg-gray-700 cursor-pointer transition-colors",
+                 active: "bg-gray-700 border-l-4 border-blue-500"
+  end
+
+  def render
+    state.channels.map do |channel|
+      is_active = state.current_channel_id == channel.id
+      div(class: s.channel_item(is_active)) do
+        span { channel.name }
+      end
+    end
+  end
+end
+```
+
+When `is_active` is `true`, the result is `"p-4 hover:bg-gray-700 cursor-pointer transition-colors bg-gray-700 border-l-4 border-blue-500"`.
+When `false`, only the base classes are applied.
+
+## Variant Styles
+
+For styles with multiple states (e.g., primary/danger buttons), use `variants:`:
+
+```ruby
+class ButtonComponent < Funicular::Component
+  styles do
+    button base: "px-4 py-2 rounded font-semibold transition-colors",
+           variants: {
+             primary: "bg-blue-600 text-white hover:bg-blue-700",
+             danger: "bg-red-600 text-white hover:bg-red-700",
+             secondary: "bg-gray-600 text-white hover:bg-gray-700",
+             ghost: "bg-transparent border border-gray-300 hover:bg-gray-100"
+           }
+  end
+
+  def render
+    div do
+      button(class: s.button(:primary)) { "Submit" }
+      button(class: s.button(:danger)) { "Delete" }
+      button(class: s.button(:secondary)) { "Cancel" }
+      button(class: s.button(:ghost)) { "Learn More" }
+    end
+  end
+end
+```
+
+You can also combine variants with props:
+
+```ruby
+class ActionButton < Funicular::Component
+  styles do
+    button base: "px-4 py-2 rounded font-semibold",
+           variants: {
+             primary: "bg-blue-600 text-white hover:bg-blue-700",
+             danger: "bg-red-600 text-white hover:bg-red-700"
+           }
+  end
+
+  def render
+    button(class: s.button(props[:variant] || :primary)) do
+      props[:label]
+    end
+  end
+end
+
+# Usage
+component(ActionButton, variant: :danger, label: "Delete")
+```
+
+## Combining Styles
+
+Chain multiple styles together using the `|` operator:
+
+```ruby
+class Sidebar < Funicular::Component
+  styles do
+    flex "flex"
+    items_center "items-center"
+    gap_2 "gap-2"
+    sidebar "w-64 bg-gray-800 text-white p-4"
+    channel_item base: "p-2 rounded hover:bg-gray-700 cursor-pointer",
+                 active: "bg-gray-700"
+  end
+
+  def render
+    div(class: s.sidebar) do
+      # Combine utility classes
+      div(class: s.flex | s.items_center | s.gap_2) do
+        span { "Channel List" }
+      end
+
+      # Mix DSL styles with custom classes
+      div(class: s.channel_item(is_active) | "mb-2" | "custom-shadow") do
+        span { "General" }
+      end
+    end
+  end
+end
+```
+
+The `|` operator:
+- Automatically filters out `nil` values
+- Perfect for conditional styling
+- Allows mixing DSL styles with raw strings
+
+### Conditional Combination
+
+```ruby
+def render
+  div(class: s.card | (state.highlighted ? "ring-2 ring-blue-500" : nil)) do
+    # Card content
+  end
+end
+```
+
+## Best Practices
+
+### 1. Keep Styles Scoped
+
+Define styles within components to avoid global namespace pollution:
+
+```ruby
+# ✅ Good: Scoped to component
+class UserCard < Funicular::Component
+  styles do
+    card "bg-white rounded shadow p-4"
+  end
+end
+
+# ❌ Avoid: Global CSS classes scattered in render
+class UserCard < Funicular::Component
+  def render
+    div(class: "bg-white rounded shadow p-4")  # Less maintainable
+  end
+end
+```
+
+### 2. Use Semantic Names
+
+```ruby
+# ✅ Good: Semantic style names
+styles do
+  primary_button "bg-blue-600 text-white px-4 py-2 rounded"
+  danger_button "bg-red-600 text-white px-4 py-2 rounded"
+end
+
+# ❌ Avoid: Generic or unclear names
+styles do
+  btn1 "bg-blue-600 text-white px-4 py-2 rounded"
+  btn2 "bg-red-600 text-white px-4 py-2 rounded"
+end
+```
+
+### 3. Group Related Styles
+
+```ruby
+styles do
+  # Layout
+  container "max-w-7xl mx-auto px-4"
+  sidebar "w-64 bg-gray-800"
+  main_content "flex-1 p-6"
+
+  # Typography
+  heading "text-2xl font-bold text-gray-900"
+  subheading "text-lg font-semibold text-gray-700"
+  body_text "text-base text-gray-600"
+
+  # Buttons
+  button base: "px-4 py-2 rounded",
+         variants: {
+           primary: "bg-blue-600 text-white",
+           secondary: "bg-gray-600 text-white"
+         }
+end
+```
+
+### 4. Extract Common Styles
+
+For styles used across multiple components, consider creating a shared module:
+
+```ruby
+module ButtonStyles
+  def self.included(base)
+    base.class_eval do
+      styles do
+        button base: "px-4 py-2 rounded font-semibold transition-colors",
+               variants: {
+                 primary: "bg-blue-600 text-white hover:bg-blue-700",
+                 danger: "bg-red-600 text-white hover:bg-red-700"
+               }
+      end
+    end
+  end
+end
+
+class MyComponent < Funicular::Component
+  include ButtonStyles
+
+  def render
+    button(class: s.button(:primary)) { "Click Me" }
+  end
+end
+```
+
+### 5. Use Tailwind (or Similar) for Utility Classes
+
+Funicular's Styles DSL works great with Tailwind CSS utility classes:
+
+```ruby
+styles do
+  card "bg-white dark:bg-gray-800 rounded-lg shadow-md p-6 hover:shadow-xl transition-shadow"
+  input "w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+end
+```
+
+### 6. Prefer Composition Over Long Class Strings
+
+```ruby
+# ✅ Good: Composed styles
+styles do
+  base_input "w-full px-3 py-2 border rounded-md"
+  focused_input "outline-none ring-2 ring-blue-500"
+end
+
+def render
+  input(class: s.base_input | s.focused_input)
+end
+
+# ❌ Avoid: One massive style
+styles do
+  input "w-full px-3 py-2 border rounded-md outline-none ring-2 ring-blue-500"
+end
+```
+
+## Key Benefits
+
+- **Scoped Styles**: Styles are defined within components, avoiding global namespace pollution
+- **Readability**: `s.button(:primary)` is more semantic than raw Tailwind classes scattered throughout render methods
+- **Maintainability**: Change styles in one place rather than hunting through render methods
+- **Type Safety**: The DSL ensures style names are consistent throughout your component
+- **Flexibility**: Mix DSL styles with raw strings when needed using the `|` operator