tombolo 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cacc9db2ac7d8ba235b9b142fcd8ff0b97bff68e85335c621ad305adb55839c
-  data.tar.gz: 04f784cf784897a241fe0b410ab4856214c8ffe6879db882028deeec8adfe591
+  metadata.gz: c83c9dbdab6b8ff99150d3fa57531514628e2c4c98ed68f655cd4cc557553429
+  data.tar.gz: 18ce866491063647ae333e0f4cb6e768cef06c843139f97df077d4301aebd1d4
 SHA512:
-  metadata.gz: 456ea07d98bb2e17a5e7dd33a926383ae84612faa4ec7d9874bb8b960d6ebfc2ece64b7c90ed82af38972a7fc45a874cbc08037e577e0cd9729f0d4268fe79fd
-  data.tar.gz: de35b3d525d13de7535a7e57bd17312263157426ea119c3b96d1008e101c7e89cbf23cd904f21bbfd2416dd060424cb0dd92c868bcfa9a884c78a09276067420
+  metadata.gz: aff5dfca04cf8bd500be3cc099b36a7a85f4d65a4b138e99f7a44ec9feb47c02ee7e65bcae57ae458ab31884d0e6ffe06eed1d6787522b54eac9a7fd248ab940
+  data.tar.gz: 16d329db50843678dacc5d8b8d50a1c20d6c453b3dec5ca5a7b98cf1058c85d3a1c1f0987c179ed22edf3d85451d52f166c881e4116a886deab1dadfb89c570c

data/README.md

@@ -1,12 +1,29 @@
 # Tombolo
 
-Minimal React component mounting for Rails, inspired by
-[react-rails](https://github.com/reactjs/react-rails).
-
-Tombolo is designed for modern Rails apps using jsbundling-rails and
-propshaft. It provides a `react_component` view helper and optional
-server-side rendering with no asset pipeline integration — just a component
-map and a few lines of JavaScript.
+[![Gem Version](https://badge.fury.io/rb/tombolo.svg)](https://badge.fury.io/rb/tombolo)
+[![npm](https://img.shields.io/npm/v/tombolo)](https://www.npmjs.com/package/tombolo)
+[![CI](https://github.com/elektronaut/tombolo/actions/workflows/build.yml/badge.svg)](https://github.com/elektronaut/tombolo/actions/workflows/build.yml)
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Tombolo is a lightweight alternative to
+[react-rails](https://github.com/reactjs/react-rails) for mounting React
+[islands](https://www.patterns.dev/posts/islands-architecture) in your Rails
+views. It provides a `react_component` view helper, client-side mounting via a
+component map, and optional server-side rendering through ExecJS.
+
+Built for React 18+, Tombolo targets modern Rails apps using
+[jsbundling-rails](https://github.com/rails/jsbundling-rails) (or any JS
+bundler) and [propshaft](https://github.com/rails/propshaft), with no asset
+pipeline integration — just register your components and write a few lines of
+JavaScript.
+
+## Compatibility
+
+| Dependency | Versions |
+|------------|----------|
+| Ruby       | >= 3.2   |
+| Rails      | >= 7.0   |
+| React      | 18, 19   |
 
 ## Installation
 
@@ -25,8 +42,9 @@ npm install tombolo
 pnpm add tombolo
 ```
 
-Run the install generator to create a config initializer and SSR entry
-point:
+Optionally, run the install generator to create a config initializer
+(`config/initializers/tombolo.rb`) and an SSR entry point
+(`app/javascript/prerender.ts`):
 
 ```sh
 bin/rails generate tombolo:install
@@ -42,11 +60,14 @@ Render a React component from any view or partial:
 <%= react_component("Greeting", props: { name: "World" }) %>
 ```
 
+This renders a `<div>` with `data-react-component` and `data-react-props`
+attributes that the JavaScript side picks up.
+
 ### Client-side mounting
 
 Tombolo takes a component map — an object mapping component names to React
-components. The easiest way to create one is a barrel file that re-exports
-your components:
+components. The easiest way to create one is a barrel file (a module that
+re-exports from other modules):
 
 ```typescript
 // app/javascript/components/index.ts
@@ -54,36 +75,44 @@ export { Greeting } from "./Greeting";
 export { SearchForm } from "./SearchForm";
 ```
 
-Import it and call `Tombolo.start` to mount components on page load:
+#### With Turbo
+
+For apps using Turbo, use `Tombolo.mount` and `Tombolo.unmount` directly:
 
 ```typescript
 import * as Tombolo from "tombolo";
 import * as components from "./components";
 
-Tombolo.start(components);
+document.addEventListener("turbo:load", () => Tombolo.mount(components));
+document.addEventListener("turbo:before-cache", () => Tombolo.unmount());
 ```
 
-Both `Tombolo.mount` and `Tombolo.unmount` accept an optional `scope`
-parameter to limit operations to a subtree of the DOM:
+#### Without Turbo
+
+For apps without Turbo, `Tombolo.start` mounts components on
+`DOMContentLoaded` (or immediately if the DOM is already loaded):
 
 ```typescript
-Tombolo.mount(components, document.getElementById("sidebar"));
+import * as Tombolo from "tombolo";
+import * as components from "./components";
+
+Tombolo.start(components);
 ```
 
-#### Turbo
+#### Scoped mounting
 
-For apps using Turbo, use `Tombolo.mount` and `Tombolo.unmount` directly:
+Both `Tombolo.mount` and `Tombolo.unmount` accept an optional `scope`
+parameter to limit operations to a subtree of the DOM:
 
 ```typescript
-import * as Tombolo from "tombolo";
-import * as components from "./components";
-
-document.addEventListener("turbo:load", () => Tombolo.mount(components));
-document.addEventListener("turbo:before-cache", () => Tombolo.unmount());
+Tombolo.mount(components, document.getElementById("sidebar"));
 ```
 
 ### Server-side rendering
 
+SSR is optional and requires the [execjs](https://github.com/rails/execjs)
+gem.
+
 Create a server entry point that registers your components:
 
 ```typescript
@@ -94,8 +123,12 @@ import * as components from "./components";
 registerServerRenderer(components);
 ```
 
-Build it with esbuild (or your bundler of choice) targeting a CommonJS
-output that ExecJS can evaluate.
+Build it with esbuild (or your bundler of choice) as a CommonJS bundle that
+ExecJS can evaluate:
+
+```sh
+esbuild app/javascript/prerender.ts --bundle --platform=neutral --outfile=app/assets/builds/prerender.js
+```
 
 Then use `prerender: true` in your views:
 
@@ -103,6 +136,10 @@ Then use `prerender: true` in your views:
 <%= react_component("Greeting", props: { name: "World" }, prerender: true) %>
 ```
 
+When a component is prerendered, the server-rendered HTML is placed inside the
+div and Tombolo uses `hydrateRoot` instead of `createRoot` on the client.
+This preserves interactivity without a full re-render.
+
 The default server bundle path is `app/assets/builds/prerender.js`. To
 customize it, add an initializer:
 
@@ -113,29 +150,50 @@ Tombolo.configure do |config|
 end
 ```
 
-## API Reference
+## Configuration
+
+```ruby
+Tombolo.configure do |config|
+  # Convert snake_case prop keys to camelCase (default: false)
+  config.camelize_props = true
 
-### npm
+  # Path to the server-side JS bundle for SSR
+  # (default: "app/assets/builds/prerender.js")
+  config.server_bundle = "app/assets/builds/prerender.js"
+end
+```
 
-#### `Tombolo.start(components)`
+`camelize_props` can also be overridden per-call:
 
-Calls `mount` on `DOMContentLoaded`, or immediately if the DOM is already
-loaded. Convenience function for apps without Turbo.
+```erb
+<%= react_component("Greeting", props: { first_name: "World" }, camelize_props: true) %>
+```
+
+## API reference
+
+### JavaScript
 
-#### `Tombolo.mount(components, scope?)`
+#### `mount(components, scope?)`
 
 Scans `scope` (default: `document`) for elements with a
-`data-react-component` attribute. For each element, looks up the component
-by name, parses props from `data-react-props`, and mounts it.
-Already-mounted elements are skipped. Missing components log a warning to
-the console.
+`data-react-component` attribute. For each element, looks up the component by
+name, parses props from `data-react-props`, and mounts it. Elements with a
+`data-react-prerender` attribute are hydrated with `hydrateRoot`; all others
+use `createRoot`. Already-mounted elements are skipped.
 
-#### `Tombolo.unmount(scope?)`
+#### `unmount(scope?)`
 
 Unmounts all tracked React roots within `scope` (default: `document`).
 
+#### `start(components)`
+
+Calls `mount` on `DOMContentLoaded`, or immediately if the DOM is already
+loaded.
+
 #### `registerServerRenderer(components)`
 
+*Imported from `tombolo/server`.*
+
 Assigns a `renderComponent(name, propsJson)` function to `globalThis`,
 making it callable from ExecJS. Used in server entry points for SSR.
 
@@ -151,15 +209,12 @@ configuration.
 
 #### `Tombolo.configure { |config| ... }`
 
-- `config.camelize_props` — Convert snake_case prop keys to camelCase.
-  Default: `false`
-- `config.server_bundle` — Path to the server-side JS bundle for SSR.
-  Default: `"app/assets/builds/prerender.js"`
+See [Configuration](#configuration) above.
 
 ## Migrating from react-rails
 
-The main difference is the helper signature. react-rails passes props as a
-positional argument, Tombolo uses a keyword argument:
+**Helper signature.** react-rails passes props as a positional argument,
+Tombolo uses a keyword argument:
 
 ```ruby
 # react-rails
@@ -169,6 +224,23 @@ react_component("Name", { title: "Hello" })
 react_component("Name", props: { title: "Hello" })
 ```
 
+**No html_options argument.** react-rails accepts a third argument for HTML
+attributes on the wrapper div. Tombolo does not support this — wrap the helper
+call in your own tag if you need custom attributes.
+
+**No asset pipeline integration.** Tombolo does not ship a component generator
+or integrate with Sprockets/Webpacker. You manage your JavaScript build
+yourself with jsbundling-rails or an equivalent.
+
+**SSR setup.** Replace any `server_rendering.js` pack with a
+`prerender.ts` entry point that calls `registerServerRenderer`. See
+[Server-side rendering](#server-side-rendering) above.
+
+## Contributing
+
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/elektronaut/tombolo).
+
 ## License
 
 MIT

data/lib/tombolo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tombolo
-  VERSION = "0.9.0"
+  VERSION = "0.9.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tombolo
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Inge Jørgensen
@@ -23,8 +23,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
-description: Drop-in replacement for react-rails with minimal footprint. Provides
-  a view helper and optional SSR via ExecJS.
+description: Lightweight alternative to react-rails for mounting React components
+  in Rails views with optional server-side rendering via ExecJS.
 email:
 - inge@elektronaut.no
 executables: []
@@ -64,5 +64,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Minimal React component mounting for Rails
+summary: Mount React components in Rails views with optional SSR
 test_files: []