reactive_views 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb9182ae58f918f62a36d2c0ea69b4ae30b2c2d6e7a517897b3ce221ea382573
+  data.tar.gz: 6828c01ab50233811706d1dfc8c3f1d961e87c72c54e4058942410f9d7cce338
+SHA512:
+  metadata.gz: ec6677f6dbe14e769bcec14f3f94bae2584573036fde8dbcc2fe4e2c098bf29d6e7b32b4f3b5bcbadb6d5d0d08baa65eb5265cfe19d5444fe6c09b2f42c3ea4d
+  data.tar.gz: 1e66dc6799b26439f3db59644b097faaf9bb52ad720f3e47bb258e0c2e40ada312e9139669ff1c8e48416d711ee1def940bf6020054a05f7bb8eb7a4c3382988

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to the ReactiveViews gem will be documented in this file.
+
+## [Unreleased]
+
+### Fixed
+- **Generator Idempotency**: The install generator can now be run multiple times safely. It properly detects and removes old `vite_client_tag` and `vite_javascript_tag` calls, replacing them with the unified `reactive_views_script_tag` helper.
+- **Helper Robustness**: The `reactive_views_script_tag` helper now gracefully handles cases where `vite_rails` is not available or misconfigured, showing helpful error messages in development and failing silently in production.
+- **Layout Transformation**: Improved regex patterns to catch all variations of Vite tags (extra whitespace, different quote styles, multiline).
+
+### Added
+- **Comprehensive Test Suite**: Full RSpec test coverage including:
+  - Unit tests for TagTransformer, Renderer, ComponentResolver, ErrorOverlay, and Helpers
+  - Integration tests for component rendering pipeline and generator
+  - Dummy Rails app for integration testing using Combustion
+  - WebMock for SSR server mocking
+  - SimpleCov for code coverage reporting
+- **Rake Tasks**: New rake tasks for test management:
+  - `rake reactive_views:test:all` - Run all tests
+  - `rake reactive_views:test:unit` - Run unit tests only
+  - `rake reactive_views:test:integration` - Run integration tests only
+  - `rake reactive_views:test:coverage` - Run with coverage report
+  - `rake reactive_views:test:clean` - Clean test artifacts
+- **Testing Documentation**: Comprehensive testing guide in `TESTING.md`
+- **Generator Force Mode**: The install generator now respects `--force` flag to skip prompts during automated setups
+
+### Changed
+- **Generator Update Logic**: The `update_application_layout` method now:
+  - Uses multiline regex patterns (`/m` flag) for robust tag detection
+  - Removes existing `reactive_views_script_tag` before adding new one to prevent duplicates
+  - Better handles edge cases like extra whitespace and comment blocks
+  - Provides clearer status messages during updates
+
+### Development
+- Added development dependencies:
+  - rspec-rails ~> 6.0
+  - capybara ~> 3.39
+  - selenium-webdriver ~> 4.16
+  - webdrivers ~> 5.3
+  - webmock ~> 3.19
+  - simplecov ~> 0.22
+  - combustion ~> 1.4
+  - sqlite3 ~> 1.4
+
+## [Previous Versions]
+
+See git history for changes in previous versions.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Elison Campos
+
+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,134 @@
+# ReactiveViews
+
+[![CI](https://github.com/elisoncampos/reactive_views/actions/workflows/ci.yml/badge.svg)](https://github.com/elisoncampos/reactive_views/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/reactive_views)](https://rubygems.org/gems/reactive_views)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+ReactiveViews lets you write React components and use them directly inside Rails views — with **server-side rendering (SSR)**, **client hydration**, and an optional **full-page `.tsx.erb` / `.jsx.erb`** pipeline. No separate frontend app required.
+
+## Disclaimer
+
+**⚠️ ReactiveViews is in beta.** Expect some breaking changes as the API and defaults settle. If you run it in production, treat the Node SSR runtime as part of your app (monitor it, capture logs, and load test SSR-heavy pages).
+
+## What you get
+
+- **React islands in ERB**: write `<UserBadge />` in `.html.erb` and get SSR + hydration.
+- **Full-page React templates**: render entire Rails pages from `.tsx.erb` / `.jsx.erb` while keeping Rails controllers, routes, and layouts.
+- **Fast SSR**: batch rendering for flat pages, tree rendering for nested component composition.
+- **Less prop plumbing**: optional TypeScript-based prop key inference for full-page pages (reduces payload size).
+- **Caching knobs**: SSR HTML caching + inference caching with pluggable cache stores.
+- **Vite-native**: dev HMR + production builds via `vite_rails`.
+
+## A quick taste
+
+### Islands inside ERB
+
+```tsx
+// app/views/components/user_badge.tsx
+type Props = { fullName: string };
+
+export default function UserBadge({ fullName }: Props) {
+  return <strong className="UserBadge">{fullName}</strong>;
+}
+```
+
+```erb
+<!-- app/views/users/show.html.erb -->
+<UserBadge fullName="<%= @user.name %>" />
+```
+
+### Full-page `.tsx.erb`
+
+```ruby
+# app/controllers/users_controller.rb
+class UsersController < ApplicationController
+  def index
+    @users = User.select(:id, :name).order(:name)
+    reactive_view_props(current_user: current_user)
+  end
+end
+```
+
+```tsx
+// app/views/users/index.tsx.erb
+interface Props {
+  users: Array<{ id: number; name: string }>;
+  current_user: { name: string } | null;
+}
+
+export default function UsersIndex({ users, current_user }: Props) {
+  return (
+    <main>
+      <h1>Users</h1>
+      {current_user ? (
+        <p>Signed in as {current_user.name}</p>
+      ) : (
+        <p>Not signed in</p>
+      )}
+      <ul>
+        {users.map((u) => (
+          <li key={u.id}>{u.name}</li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+```
+
+## Install (5 minutes)
+
+1. Add the gem + install:
+
+```ruby
+gem "reactive_views"
+```
+
+```bash
+bundle install
+```
+
+2. Run the installer:
+
+```bash
+bundle exec rails generate reactive_views:install
+```
+
+3. Start dev:
+
+```bash
+bin/dev
+```
+
+That runs Rails + Vite + the SSR server together.
+
+For the layout helper and a full walkthrough, see [`docs/getting-started.md`](docs/getting-started.md).
+
+## Documentation
+
+Start at [`docs/README.md`](docs/README.md). Handy links:
+
+- **Quick start:** [`docs/getting-started.md`](docs/getting-started.md)
+- **Islands in ERB:** [`docs/islands.md`](docs/islands.md)
+- **Full-page `.tsx.erb` / `.jsx.erb`:** [`docs/full-page-tsx-erb.md`](docs/full-page-tsx-erb.md)
+- **Configuration:** [`docs/configuration.md`](docs/configuration.md)
+- **SSR runtime & process management:** [`docs/ssr.md`](docs/ssr.md)
+- **Caching:** [`docs/caching.md`](docs/caching.md)
+- **Production deployment:** [`docs/production-deployment.md`](docs/production-deployment.md)
+- **Troubleshooting:** [`docs/troubleshooting.md`](docs/troubleshooting.md)
+- **Security considerations:** [`docs/security.md`](docs/security.md)
+- **API reference:** [`docs/api-reference.md`](docs/api-reference.md)
+
+## Before you ship
+
+- Read [`docs/security.md`](docs/security.md) (props are public; SSR should stay private).
+- Read [`docs/production-deployment.md`](docs/production-deployment.md) (assets, SSR process strategy, what to monitor).
+
+## Contributing
+
+At this time, we are only accepting bug reports. If you encounter any issues or have suggestions, please open an issue on our [GitHub repository](https://github.com/elisoncampos/reactive_views/issues).
+
+We appreciate your feedback and contributions to help improve ReactiveViews!
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/reactive_views/bundles_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module ReactiveViews
+  class BundlesController < ActionController::Base
+    # Proxy full-page bundle requests to the local SSR server.
+    # This allows the client to fetch bundles via same-origin requests,
+    # even when the SSR server is only listening on localhost.
+    def show
+      bundle_key = params[:id]
+
+      # Validate bundle key format (should be a SHA1 hash)
+      unless bundle_key.match?(/\A[a-f0-9]{40}\z/)
+        render plain: "Invalid bundle key", status: :bad_request
+        return
+      end
+
+      # Ensure SSR process is running
+      SsrProcess.ensure_running
+
+      # Proxy the request to the SSR server
+      ssr_url = ReactiveViews.config.ssr_url
+      uri = URI.parse("#{ssr_url}/full-page-bundles/#{bundle_key}.js")
+
+      begin
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.open_timeout = 5
+        http.read_timeout = 10
+
+        response = http.get(uri.path)
+
+        if response.is_a?(Net::HTTPSuccess)
+          # Stream the JavaScript bundle back to the client
+          render body: response.body,
+                 content_type: "application/javascript",
+                 status: :ok
+        else
+          render plain: "Bundle not found", status: :not_found
+        end
+      rescue Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout => e
+        Rails.logger.error("[ReactiveViews] Bundle proxy error: #{e.message}")
+        render plain: "SSR server unavailable", status: :service_unavailable
+      end
+    end
+  end
+end

data/app/frontend/reactive_views/boot.ts

@@ -0,0 +1,215 @@
+import React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+
+type IslandSpec = {
+  id: string;
+  component: string;
+  el: Element;
+};
+
+type ReactiveViewsGlobal = {
+  react?: typeof React;
+  hydrateRoot?: typeof hydrateRoot;
+  ssrUrl?: string;
+  hydratedPages?: string[];
+  lastPageError?: string;
+};
+
+declare global {
+  interface Window {
+    __REACTIVE_VIEWS__?: ReactiveViewsGlobal;
+  }
+}
+
+const globalRV: ReactiveViewsGlobal = (window.__REACTIVE_VIEWS__ ||= {});
+globalRV.react = React;
+globalRV.hydrateRoot = hydrateRoot;
+globalRV.hydratedPages ||= [];
+
+function readProps(uuid: string) {
+  const script = document.querySelector(`script[type="application/json"][data-island-uuid="${uuid}"]`);
+  if (!script) return {};
+  try {
+    return JSON.parse(script.textContent || '{}');
+  } catch (_e) {
+    return {};
+  }
+}
+
+type PageMetadata = {
+  props?: Record<string, unknown>;
+  bundle?: string;
+};
+
+function readPageMetadata(uuid: string): PageMetadata {
+  const script = document.querySelector(`script[type="application/json"][data-page-uuid="${uuid}"]`);
+  if (!script) return {};
+  try {
+    return JSON.parse(script.textContent || '{}');
+  } catch (_e) {
+    return {};
+  }
+}
+
+function toPath(name: string): string {
+  // Convert PascalCase and dot notation to snake_case path
+  const parts = name.split('.');
+  const snake = (s: string) => s.replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2').replace(/([a-z\d])([A-Z])/g, '$1_$2').replace(/-/g, '_').toLowerCase();
+  return parts.map(snake).join('/');
+}
+
+// Import all components eagerly so they are available for hydration
+const rawComponentsFromViews = import.meta.glob('../../views/components/**/*.{tsx,jsx,ts,js}', { 
+  eager: true,
+});
+const rawComponentsFromJs = import.meta.glob('../components/**/*.{tsx,jsx,ts,js}', { 
+  eager: true,
+});
+
+// Normalize paths to match the absolute aliased paths that loadComponent expects
+const componentsFromViews: Record<string, any> = {};
+const componentsFromJs: Record<string, any> = {};
+
+for (const [path, module] of Object.entries(rawComponentsFromViews)) {
+  const normalized = path.replace('../../views/components/', '/app/views/components/');
+  componentsFromViews[normalized] = (module as any).default;
+}
+
+for (const [path, module] of Object.entries(rawComponentsFromJs)) {
+  const normalized = path.replace('../components/', '/app/javascript/components/');
+  componentsFromJs[normalized] = (module as any).default;
+}
+
+async function loadComponent(name: string) {
+  // Attempt both conventional locations; try multiple filename shapes and extensions
+  const rel = toPath(name);
+  const leaf = rel.split('/').pop() as string;
+  const bases = ['/app/views/components', '/app/javascript/components'];
+  const exts = ['.tsx', '.jsx', '.ts', '.js'];
+
+  // Combine both glob maps
+  const allComponents = { ...componentsFromViews, ...componentsFromJs };
+
+  // Try both the original name (e.g., "InteractiveCounter") and snake_case ("interactive_counter")
+  const nameVariants = [name, rel];
+  const leafVariants = [name, leaf];
+
+  for (const base of bases) {
+    for (let i = 0; i < nameVariants.length; i++) {
+      const nameVar = nameVariants[i];
+      const leafVar = leafVariants[i];
+      
+      for (const ext of exts) {
+        const candidates = [
+          `${base}/${nameVar}${ext}`,
+          `${base}/${nameVar}/index${ext}`,
+          `${base}/${nameVar}/${leafVar}${ext}`,
+        ];
+        for (const path of candidates) {
+          // Check if this path exists in our glob imports
+          if (allComponents[path]) {
+            // Component is already loaded with eager: true
+            // The .default was already extracted during normalization
+            return allComponents[path];
+          }
+        }
+      }
+    }
+  }
+
+  throw new Error(`Component not found on client: ${name}`);
+}
+
+function resolveSsrUrl() {
+  if (globalRV.ssrUrl) return globalRV.ssrUrl.replace(/\/$/, '');
+  const meta = document.querySelector('meta[name="reactive-views-ssr-url"]');
+  if (meta?.getAttribute('content')) {
+    return meta.getAttribute('content')!.replace(/\/$/, '');
+  }
+  return 'http://localhost:5175';
+}
+
+async function hydrateFullPages() {
+  const nodes = Array.from(document.querySelectorAll<HTMLElement>('[data-reactive-page="true"]'));
+  for (const node of nodes) {
+    const uuid = node.dataset.pageUuid;
+    if (!uuid) continue;
+
+    // Skip if already hydrated
+    if (node.dataset.reactiveHydrated === 'true') continue;
+
+    const metadata = readPageMetadata(uuid);
+    if (!metadata.bundle) continue;
+
+    const ssrUrl = resolveSsrUrl();
+    const moduleUrl = `${ssrUrl}/full-page-bundles/${metadata.bundle}.js`;
+
+    try {
+      if (import.meta.env?.DEV) {
+        console.log(`[reactive_views] Hydrating full page bundle: ${metadata.bundle}`);
+      }
+      const mod = await import(/* @vite-ignore */ moduleUrl);
+      const Comp = mod.default || mod.Component || mod;
+      hydrateRoot(node, React.createElement(Comp, metadata.props || {}));
+      if (import.meta.env?.DEV) {
+        console.log(`[reactive_views] Hydrated full page bundle ${metadata.bundle}`);
+      }
+      globalRV.hydratedPages!.push(uuid);
+      node.dataset.reactiveHydrated = "true";
+    } catch (e) {
+      if (import.meta.env?.DEV) {
+        console.error(`[reactive_views] Failed to hydrate full page bundle: ${metadata.bundle}`, e);
+      }
+      globalRV.lastPageError = e instanceof Error ? e.stack : String(e);
+    }
+  }
+}
+
+async function hydrateIslands() {
+  const nodes = Array.from(document.querySelectorAll('[data-island-uuid][data-component]'));
+  for (const node of nodes) {
+    const el = node as HTMLElement;
+    
+    // Skip if already hydrated
+    if (el.dataset.reactiveHydrated === 'true') continue;
+    
+    const uuid = el.dataset.islandUuid!;
+    const component = el.dataset.component!;
+    try {
+      const Comp = await loadComponent(component);
+      const props = readProps(uuid);
+      hydrateRoot(el, React.createElement(Comp, props));
+      el.dataset.reactiveHydrated = 'true';
+    } catch (e) {
+      if (import.meta.env?.DEV) {
+        console.error(`[reactive_views] Failed to hydrate component: ${component}`, e);
+        console.error(`[reactive_views] Make sure vite.config.ts has resolve.alias configured for /app/views/components and /app/javascript/components`);
+      }
+    }
+  }
+}
+
+async function hydrateAll() {
+  await hydrateFullPages();
+  await hydrateIslands();
+}
+
+// Initial hydration
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', hydrateAll);
+} else {
+  hydrateAll();
+}
+
+// Turbo integration: re-hydrate after Turbo navigations
+// This ensures React components work correctly with Turbo Drive and Turbo Frames
+document.addEventListener('turbo:load', hydrateAll);
+document.addEventListener('turbo:frame-load', hydrateAll);
+
+// Clean up before Turbo caches the page for back/forward navigation
+// Without this, restored pages have data-reactive-hydrated="true" but no actual React instances
+document.addEventListener('turbo:before-cache', () => {
+  document.querySelectorAll('[data-reactive-hydrated]').forEach(el => {
+    el.removeAttribute('data-reactive-hydrated');
+  });
+});

data/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+ReactiveViews::Engine.routes.draw do
+  # Proxy full-page bundle requests to the SSR server
+  # The client requests: /reactive_views/full-page-bundles/:bundle_key.js
+  # We match both with and without the .js extension for flexibility
+  get "full-page-bundles/:id", to: "bundles#show", as: :bundle,
+      constraints: { id: /[a-f0-9]+/ },
+      defaults: { format: "js" }
+end