@live-react-islands/core 0.1.0 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 David Czaplinski
+Copyright (c) 2026 David Czaplinski
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,454 @@
+# Live React Islands
+
+**React-powered interactive islands** inside Phoenix LiveView. Harness the NPM ecosystem with server-driven state, real-time streams and zero-lag forms + SSR.
+
+![Banner](https://raw.githubusercontent.com/dcza/live-react-islands/main/docs/repository-open-graph.png)
+
+## Why Live React Islands?
+
+**The best of both worlds!** ✨
+
+Phoenix LiveView is excellent for server-driven UIs, but sometimes you need the rich interactivity of React for specific components. Live React Islands lets you:
+
+- Use React components as "islands" within your LiveView templates
+- Maintain server-side state in Elixir while rendering in React
+- Send events from React to Elixir and push props back
+- Use forms and streams in React with dedicated hooks
+- Share global state across multiple islands
+- Optionally server-side render for faster loads, SEO and no flicker
+
+## Comparison
+
+Choose Live React Islands when you need rich, interactive React components without giving up LiveView’s server-driven simplicity.
+
+| Feature                | LiveView Only                              | LiveView + Alpine    | Live React Islands (this)              | Pure SPA (Next.js/Vite) |
+| :--------------------- | :----------------------------------------- | :------------------- | :------------------------------------- | :---------------------- |
+| **UI Ecosystem**       | Limited (HEEX/Custom)                      | Small (Alpine kits)  | **Infinite (NPM/React)**               | **Infinite (NPM)**      |
+| **Interactivity**      | Server-Roundtrip (JS hooks for edge cases) | Simple Client-side   | **High-Fidelity / Fluid**              | High-Fidelity / Fluid   |
+| **State Management**   | Single (Server)                            | Fragmented           | **Single (Server-Led)**                | Dual (API + Client)     |
+| **Initial Load / SEO** | Instant                                    | Instant              | **Instant (SSR-enabled)**              | Slow / Complex SSR      |
+| **JS Bundle Size**     | ~0kb (Core only)                           | Small (+15kb)        | **Large (React: ~100–150 kB gzipped)** | Large                   |
+| **Developer Speed**    | Very High                                  | High (until complex) | **High (Asset Reuse)**                 | Low (API Plumbing)      |
+| **Component Logic**    | Elixir Only                                | Mixed (Strings)      | **JSX (Encapsulated)**                 | JSX                     |
+| **Complexity Ceiling** | Struggles with app-like complexity         | Hits wall on "State" | **High**                               | Very High               |
+
+## When NOT to Use Live React Islands
+
+- If your UI is mostly static or CRUD-heavy, plain LiveView is simpler and faster.
+- If you only need light client-side behavior (toggles, dropdowns), LiveView + Alpine may be sufficient.
+- If your application requires full offline support or heavy client-side state, a traditional SPA may be a better fit.
+
+## Installation
+
+### Elixir
+
+Add to your `mix.exs`:
+
+```elixir
+def deps do
+  [
+    {:live_react_islands, "~> 0.1.0"},
+    # For development SSR (optional):
+    {:live_react_islands_ssr_vite, "~> 0.1.0", only: :dev},
+    # For production SSR (optional):
+    {:live_react_islands_ssr_deno, "~> 0.1.0", only: :prod}
+  ]
+end
+```
+
+### JavaScript
+
+```bash
+npm install @live-react-islands/core
+# For development SSR (optional):
+npm install --save-dev @live-react-islands/vite-plugin-ssr
+```
+
+## Quick Start
+
+### 1. Create a React Component
+
+```jsx
+// src/islands/Counter.jsx
+const Counter = ({ count, title, pushEvent }) => {
+  return (
+    <div>
+      <h2>{title}</h2>
+      <p>Count: {count}</p>
+      <button onClick={() => pushEvent("increment", {})}>+1</button>
+    </div>
+  );
+};
+
+export default Counter;
+```
+
+### 2. Set Up the LiveView Hooks
+
+```jsx
+// src/islands/index.js
+export default { Counter: () => import("./Counter") };
+```
+
+Islands can be lazy loaded to only load the JS used on the page.
+
+```jsx
+// src/main.jsx
+import { createHooks } from "@live-react-islands/core";
+import islands from "./islands";
+
+const islandHooks = createHooks({ islands });
+
+// Add to your LiveSocket
+let liveSocket = new LiveSocket("/live", Socket, {
+  hooks: { ...islandHooks },
+});
+```
+
+### 3. Create an Elixir Component
+
+```elixir
+defmodule MyAppWeb.Components.CounterIsland do
+  use LiveReactIslands.Component,
+    component: "Counter",
+    props: %{count: 0, title: "My Counter"}
+
+  def handle_event("increment", _params, socket) do
+    new_count = socket.assigns.count + 1
+    {:noreply, update_prop(socket, :count, new_count)}
+  end
+end
+```
+
+### 4. Use in Your LiveView
+
+```elixir
+defmodule MyAppWeb.CounterLive do
+  use MyAppWeb, :live_view
+  use LiveReactIslands.LiveView
+
+  def render(assigns) do
+    ~H"""
+    <.live_component module={MyAppWeb.Components.CounterIsland} id="counter-1" />
+    """
+  end
+end
+```
+
+## How It Works
+
+**React components receive these props automatically:**
+
+| Prop                 | Description                       |
+| -------------------- | --------------------------------- |
+| `id`                 | The island's unique identifier    |
+| `pushEvent`          | Function to send events to Elixir |
+| All defined props    | Current values from Elixir        |
+| All consumed globals | Current global state values       |
+
+## Features
+
+### Props
+
+Define props with default values. Props can be set from the template or updated from event handlers:
+
+```elixir
+use LiveReactIslands.Component,
+  component: "Counter",
+  props: %{count: 0, title: "Default Title"}
+```
+
+**Elixir components can override `init/2` for dynamic initialization:**
+
+```elixir
+def init(assigns, socket) do
+  # Called once on mount, before SSR and first render
+  socket
+  |> update_prop(:computed, compute_value(assigns))
+end
+```
+
+**Updating props from Elixir:**
+
+```elixir
+def handle_event("increment", _, socket) do
+  {:noreply, update_prop(socket, :count, socket.assigns.count + 1)}
+end
+```
+
+**Passing props from templates:**
+
+```heex
+<.live_component module={CounterIsland} id="counter-1" title="Custom Title" />
+```
+
+Once a prop is set from outside the component any `update_prop` call on it will raise an error to prevent a nasty set of bugs. To just initialize the component use `init_[prop]` to set the value once and then the component takes over.
+
+```heex
+<.live_component module={CounterIsland} id="counter-1" init_count={5} />
+```
+
+### Events
+
+Send events from React to Elixir using `pushEvent`:
+
+```jsx
+// React
+<button onClick={() => pushEvent("save", { data: formData })}>Save</button>
+```
+
+```elixir
+# Elixir
+def handle_event("save", %{"data" => data}, socket) do
+  # Handle the event
+  {:noreply, socket}
+end
+```
+
+### Global State
+
+Share state across multiple islands. When a global changes, all islands that use it automatically rerender.
+
+**Set up in your LiveView:**
+
+```elixir
+defmodule MyAppWeb.DashboardLive do
+  use MyAppWeb, :live_view
+  use LiveReactIslands.LiveView, expose_globals: [:user, :theme]
+
+  def mount(_params, session, socket) do
+    {:ok, assign(socket, user: get_user(session), theme: "light")}
+  end
+end
+```
+
+**Consume in your island:**
+
+```elixir
+use LiveReactIslands.Component,
+  component: "Header",
+  props: %{},
+  globals: [:user, :theme]
+```
+
+**Optional globals** (won't error if not set):
+
+```elixir
+globals: [:user?]  # The ? suffix makes it optional
+```
+
+The globals are passed as props to your React component:
+
+```jsx
+const Header = ({ user, theme }) => (
+  <header className={theme}>Welcome, {user.name}</header>
+);
+```
+
+### Forms with Server Validation
+
+Build forms with React UI and Elixir/Ecto validation. Input is collected client side with zero typing latency and send to Elixir for validation. Errors from the changeset get pushed back to React.
+
+The `useForm` hook implements a "Validation Lock" pattern: Updates are versioned and `isValid` will only be true until the server confirms the current form state is valid.
+
+**Elixir component:**
+
+```elixir
+defmodule MyAppWeb.Components.ContactFormIsland do
+  use LiveReactIslands.Component,
+    component: "ContactForm",
+    props: %{form: %{}}
+
+  alias MyApp.Contact
+
+  def init(_assigns, socket) do
+    changeset = Contact.changeset(%Contact{}, %{})
+    socket |> init_form(:form, changeset)
+  end
+
+  def handle_form(:validate, :form, attrs, socket) do
+    changeset = Contact.changeset(%Contact{}, attrs)
+    {:noreply, update_form(socket, :form, changeset)}
+  end
+
+  def handle_form(:submit, :form, attrs, socket) do
+    case Contact.create(attrs) do
+      {:ok, _contact} ->
+        {:noreply, init_form(socket, :form, Contact.changeset(%Contact{}, %{}))}
+      {:error, changeset} ->
+        {:noreply, update_form(socket, :form, changeset)}
+    end
+  end
+end
+```
+
+**React component:**
+
+```jsx
+import { useForm } from "@live-react-islands/core";
+
+const ContactForm = ({ form, pushEvent }) => {
+  const {
+    getFieldProps,
+    getError,
+    isRequired,
+    isTouched,
+    handleSubmit,
+    isValid,
+  } = useForm(form, pushEvent);
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input {...getFieldProps("name")} />
+      {isTouched("name") && getError("name") && (
+        <span className="error">{getError("name")}</span>
+      )}
+
+      <input {...getFieldProps("email")} type="email" />
+      {isTouched("email") && getError("email") && (
+        <span className="error">{getError("email")}</span>
+      )}
+
+      <button type="submit" disabled={!isValid}>
+        Submit
+      </button>
+    </form>
+  );
+};
+```
+
+**`useForm` returns:**
+
+| Property                | Description                                           |
+| ----------------------- | ----------------------------------------------------- |
+| `values`                | Current form values                                   |
+| `errors`                | Validation errors by field                            |
+| `touched`               | Fields the user has interacted with                   |
+| `getFieldProps(name)`   | Props to spread on inputs (`value`, `onChange`, etc.) |
+| `getError(name)`        | First error message for a field                       |
+| `isRequired(name)`      | Whether a field is required                           |
+| `isTouched(name)`       | Whether user has modified this field                  |
+| `setField(name, value)` | Programmatically set a field value                    |
+| `handleSubmit`          | Form submit handler                                   |
+| `reset()`               | Reset form to server values                           |
+| `isSyncing`             | True while waiting for server validation              |
+| `isValid`               | True only when synced AND server says valid           |
+
+### Streams
+
+Stream data to React components for real-time updates like feeds, chat, or infinite scrolling:
+
+**Define a stream prop:**
+
+```elixir
+use LiveReactIslands.Component,
+  component: "MessageList",
+  props: %{
+    messages: {:stream, default: []}
+  }
+```
+
+**Push stream events from Elixir:**
+
+```elixir
+# Insert new item (prepends by default)
+socket |> stream_insert(:messages, %{id: 1, text: "Hello"})
+
+# Update existing item
+socket |> stream_update(:messages, %{id: 1, text: "Hello, edited"})
+
+# Delete an item
+socket |> stream_delete(:messages, 1)
+
+# Reset the entire stream
+socket |> stream_reset(:messages)
+```
+
+**Consume in React:**
+
+```jsx
+import { useStream } from "@live-react-islands/core";
+
+const MessageList = ({ messages: messagesHandle }) => {
+  const messages = useStream(messagesHandle, { limit: 100 });
+
+  return (
+    <ul>
+      {messages.map((msg) => (
+        <li key={msg.id}>{msg.text}</li>
+      ))}
+    </ul>
+  );
+};
+```
+
+### Shared Context
+
+Islands using `:none` (default) or `:overwrite` SSR strategies render into a shared React root via portals. This enables powerful patterns like drag-and-drop between islands, shared state managers, or animation libraries that need to coordinate across components.
+
+**Wrap all islands in a shared context:**
+
+```jsx
+// src/main.jsx
+import { createHooks } from "@live-react-islands/core";
+import { DndProvider } from "react-beautiful-dnd";
+import islands from "./islands";
+
+const SharedContextProvider = ({ children }) => (
+  <DndProvider backend={HTML5Backend}>{children}</DndProvider>
+);
+
+const islandHooks = createHooks({
+  islands,
+  SharedContextProvider,
+});
+```
+
+Now all your islands can participate in drag-and-drop with each other, even though they're scattered across your LiveView template.
+
+> **Note:** Islands using `:hydrate_root` SSR strategy have their own isolated React root and do not participate in the shared context. Use `:overwrite` or `:none` if you need context sharing between islands.
+
+### Server-Side Rendering (SSR)
+
+SSR improves initial page load performance by rendering React components on the server.
+
+```elixir
+use LiveReactIslands.Component,
+  component: "Counter",
+  props: %{count: 0},
+  ssr_strategy: :overwrite  # or :hydrate_root or :none (default)
+```
+
+| Strategy        | Shared Root | Best For                                                                |
+| --------------- | ----------- | ----------------------------------------------------------------------- |
+| `:none`         | Yes         | Interactive components where initial render doesn't matter              |
+| `:overwrite`    | Yes         | Most islands, especially when you need cross-island context (e.g., DnD) |
+| `:hydrate_root` | No          | Large islands where you want to avoid the overwrite flash               |
+
+> ⚠️ SSR is optional. Many islands work perfectly without it. Enable SSR when initial paint, SEO, or perceived performance matter.
+
+See the **[SSR Guide](https://github.com/dcza/live-react-islands/blob/main/docs/SSR.md)** for complete setup instructions, caching strategies, and custom renderer implementation.
+
+## Requirements
+
+- Elixir >= 1.14
+- Phoenix LiveView >= 1.0
+- React 18 or 19
+- Any JavaScript bundler (built-in SSR plugin for Vite)
+
+### Running Examples
+
+```bash
+cd examples/vite-example
+mix deps.get
+cd assets && yarn install && yarn dev  # in one terminal
+cd .. && mix phx.server                # in another terminal
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/dcza/live-react-islands/blob/main/CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT License - see [LICENSE](https://github.com/dcza/live-react-islands/blob/main/LICENSE) for details.

package/dist/createHooks.d.ts

@@ -3,7 +3,9 @@ import { type IslandsMap, type ContextProviderComponent } from "./types";
 interface LiveViewHook {
     el: HTMLElement;
     liveSocket: {
-        on: (event: string, callback: (e: Event) => void) => void;
+        on: (event: string, callback: (e: CustomEvent<{
+            kind: string;
+        }>) => void) => void;
     };
     pushEvent: (event: string, payload: any, callback?: (reply: any, ref: any) => void) => void;
     pushEventTo: (target: string, event: string, payload: any) => void;

package/dist/createHooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createHooks.d.ts","sourceRoot":"","sources":["../src/createHooks.ts"],"names":[],"mappings":"AAAA,OAAuB,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EACL,KAAK,UAAU,EAGf,KAAK,wBAAwB,EAM9B,MAAM,SAAS,CAAC;AAMjB,UAAU,YAAY;IACpB,EAAE,EAAE,WAAW,CAAC;IAChB,UAAU,EAAE;QACV,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,KAAK,IAAI,CAAC;KAC3D,CAAC;IACF,SAAS,EAAE,CACT,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,GAAG,EACZ,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,KACtC,IAAI,CAAC;IACV,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACnE,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,KAAK,IAAI,CAAC;CACrE;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,UAAU,CAAC;IACpB,qBAAqB,CAAC,EAAE,wBAAwB,CAAC;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAwED,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EAAE,UAAe,EACxB,qBAA2C,EAC3C,OAAwB,GACzB,EAAE,kBAAkB;;iBASR,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI;kBAC3B,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI;mBAC3B,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI;;EA0N1C"}
+{"version":3,"file":"createHooks.d.ts","sourceRoot":"","sources":["../src/createHooks.ts"],"names":[],"mappings":"AAAA,OAAuB,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EACL,KAAK,UAAU,EAGf,KAAK,wBAAwB,EAM9B,MAAM,SAAS,CAAC;AAMjB,UAAU,YAAY;IACpB,EAAE,EAAE,WAAW,CAAC;IAChB,UAAU,EAAE;QACV,EAAE,EAAE,CACF,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,KAAK,IAAI,KACjD,IAAI,CAAC;KACX,CAAC;IACF,SAAS,EAAE,CACT,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,GAAG,EACZ,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,IAAI,KACtC,IAAI,CAAC;IACV,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,IAAI,CAAC;IACnE,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,KAAK,IAAI,CAAC;CACrE;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,UAAU,CAAC;IACpB,qBAAqB,CAAC,EAAE,wBAAwB,CAAC;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAwED,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EAAE,UAAe,EACxB,qBAA2C,EAC3C,OAAwB,GACzB,EAAE,kBAAkB;;iBASR,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI;kBAC3B,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI;mBAC3B,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI;;EAgO1C"}

package/dist/index.esm.js

@@ -380,7 +380,14 @@ function createHooks({ islands: islandsMap = {}, SharedContextProvider = NullCon
             }
             if (!navigationListenerAttached) {
                 navigationListenerAttached = true;
-                this.liveSocket.on("phx:page-loading-start", () => {
+                this.liveSocket.on("phx:page-loading-start", (e) => {
+                    // Patches (e.g. push_patch tab switches) stay within the same
+                    // LiveView mount and globals version counter, so islands that
+                    // remain mounted through the patch must keep their cached
+                    // globals. Only a real navigation (new mount, version resets
+                    // to 0 server-side) needs the stale client-side version cleared.
+                    if (e.detail?.kind === "patch")
+                        return;
                     globalsRequested = false;
                     managerState = manager.resetGlobals(managerState);
                 });
@@ -469,7 +476,7 @@ function createHooks({ islands: islandsMap = {}, SharedContextProvider = NullCon
             const el = this.el;
             pendingMounts.add(elId);
             (async () => {
-                const islandConfig = await resolveIslandConfig(islandsMap, componentName, SharedContextProvider);
+                const islandConfig = await resolveIslandConfig(islandsMap, componentName, NullContextProvider$1);
                 if (!pendingMounts.has(elId))
                     return;
                 pendingMounts.delete(elId);