diff --git a/CHANGELOG.md b/CHANGELOG.md index ee47e8e3..d606f2a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,67 @@ See [Conventional Commits](Https://conventionalcommits.org) for commit guideline +## [Unreleased] + +### Features: + +* **Link Component**: Add React Link component for Phoenix LiveView navigation + + The new `Link` component provides seamless navigation within Phoenix LiveView applications, supporting all LiveView navigation patterns: + + - `href` - Traditional browser navigation (full page reload) + - `patch` - Patch current LiveView (calls handle_params) + - `navigate` - Navigate to different LiveView (same live_session) + - `replace` - Replace browser history instead of push + + ```jsx + import { Link } from "live_react"; + + External Link + Patch Current LV + Navigate to Other LV + Replace History + ``` + +### 🔄 Upgrade Guide for Existing Projects + +#### ✅ Automatic Updates (via `mix deps.update`) +These files are automatically updated when you update the `live_react` dependency: +- `assets/js/live_react/link.jsx` - New Link component +- `assets/js/live_react/index.mjs` - Updated exports +- `assets/js/live_react/index.d.mts` - New TypeScript definitions + +#### 📝 Use Link in your React components + +```javascript +// assets/react-components/index.js +import { Link } from "live_react"; + +export default { + // ... your existing components + Link, // Add this line +}; +``` + +#### 🚀 Quick Start (No Manual Updates Needed) +You can start using the Link component immediately after updating: + +```elixir +# In any LiveView template +<.react name="Link" href="/some-page">Click me +<.react name="Link" patch="/current?tab=new">Patch +<.react name="Link" navigate="/other-live-view">Navigate +``` + +#### 📊 What's Updated in live_react_examples +If you're using the examples app as reference, these files have been updated: +- Added `/link-demo` and `/link-usage` routes +- Updated navigation in layout +- Added demo LiveViews and React components +- Updated documentation + +--- + ## [v1.0.1](https://github.com/mrdotb/live_react/compare/v1.0.1...v1.0.0) (2025-04-20) ### Bug Fixes: diff --git a/README.md b/README.md index 0d6a31f0..bf82a7e3 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ React inside Phoenix LiveView. - 💀 **Dead View** Support - 🐌 **Lazy-loading** React Components - 🦥 **Slot** Interoperability +- 🔗 **Link Component** for LiveView Navigation - 🚀 **Amazing DX** with Vite ## Resources diff --git a/assets/copy/react-components/index.js b/assets/copy/react-components/index.js index 1a96281a..46d1cad4 100644 --- a/assets/copy/react-components/index.js +++ b/assets/copy/react-components/index.js @@ -1,5 +1,9 @@ import { Simple } from "./simple"; +import { LinkExample } from "./link-example"; +import { Link } from "live_react"; export default { Simple, + LinkExample, + Link, }; diff --git a/assets/copy/react-components/link-example.jsx b/assets/copy/react-components/link-example.jsx new file mode 100644 index 00000000..8ec805c5 --- /dev/null +++ b/assets/copy/react-components/link-example.jsx @@ -0,0 +1,40 @@ +import React from "react"; +import { Link } from "live_react"; + +export function LinkExample({}) { + return ( +
+ + External Link (full page reload) + +
+ ++ + Patch Link (same LiveView, calls handle_params) + +
+ ++ + Navigate Link (different LiveView, same session) + +
+ ++ + Replace History (navigate with replace) + +
+
+ Current path: {currentPath}
+
+ These links cause full page reloads, just like regular HTML links. +
++ Patch stays in the same LiveView process, calls handle_params. +
++ Navigate to different LiveViews within the same live_session. +
++ Replace browser history instead of adding new entries. +
++ Use your browser's back/forward buttons to test navigation behavior. + Notice the difference between href (full reload), patch (same process), + and navigate (new process) links. +
+Current Path: <%= @current_path %>
+Current Tab: <%= @current_tab %>
+URL Params: <%= inspect(@params) %>
+LiveView Process: <%= inspect(self()) %>
+Mount Count: <%= @mount_count %>
+Params Update Count: <%= @params_update_count %>
++ 🔄 This page was reached via history replace - check your browser's back button! +
++ ✅ This demonstrates patch navigation - same process, different params! +
++ This demonstrates using the Link component directly in LiveView templates + alongside regular Phoenix link helpers. +
+URL Params: <%= inspect(@params) %>
+LiveView Process: <%= inspect(self()) %>
+ + <%= if @params["phoenix"] do %> ++ 🔵 Navigated here via Phoenix <%= @params["phoenix"] %> link +
++ ⚛️ Navigated here via React <%= @params["react"] %> link +
+