feat: add Hyperlink::with_label(...)

jetpham · jetpham · commit 78a43bd61db2 · 2026-03-24T13:48:19.000-07:00
diff --git a/.direnv/bin/nix-direnv-reload b/.direnv/bin/nix-direnv-reload
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -e
+if [[ ! -d "/home/jet/Documents/ratzilla" ]]; then
+  echo "Cannot find source directory; Did you move it?"
+  echo "(Looking for "/home/jet/Documents/ratzilla")"
+  echo 'Cannot force reload with this script - use "direnv reload" manually and then try again'
+  exit 1
+fi
+
+# rebuild the cache forcefully
+_nix_direnv_force_reload=1 direnv exec "/home/jet/Documents/ratzilla" true
+
+# Update the mtime for .envrc.
+# This will cause direnv to reload again - but without re-building.
+touch "/home/jet/Documents/ratzilla/.envrc"
+
+# Also update the timestamp of whatever profile_rc we have.
+# This makes sure that we know we are up to date.
+touch -r "/home/jet/Documents/ratzilla/.envrc" "/home/jet/Documents/ratzilla/.direnv"/*.rc
diff --git a/.direnv/flake-inputs/01x5k4nlxcpyd85nnr0b9gm89rm8ff4x-source b/.direnv/flake-inputs/01x5k4nlxcpyd85nnr0b9gm89rm8ff4x-source
@@ -0,0 +1 @@
+/nix/store/01x5k4nlxcpyd85nnr0b9gm89rm8ff4x-source
diff --git a/.direnv/flake-inputs/0d3h8gi2q46fb4l563h6pginjw2a90r4-source b/.direnv/flake-inputs/0d3h8gi2q46fb4l563h6pginjw2a90r4-source
@@ -0,0 +1 @@
+/nix/store/0d3h8gi2q46fb4l563h6pginjw2a90r4-source
diff --git a/.direnv/flake-inputs/4f3q0m4zz7k7si8cga2bwvj3x194zygp-source b/.direnv/flake-inputs/4f3q0m4zz7k7si8cga2bwvj3x194zygp-source
@@ -0,0 +1 @@
+/nix/store/4f3q0m4zz7k7si8cga2bwvj3x194zygp-source
diff --git a/.direnv/flake-inputs/lvh1shxv1jhm7iacffl2iliyza2pfmn0-source b/.direnv/flake-inputs/lvh1shxv1jhm7iacffl2iliyza2pfmn0-source
@@ -0,0 +1 @@
+/nix/store/lvh1shxv1jhm7iacffl2iliyza2pfmn0-source
diff --git a/.direnv/flake-inputs/s7bvgynzfisna3jdq2cr4jx73xnhxs27-source b/.direnv/flake-inputs/s7bvgynzfisna3jdq2cr4jx73xnhxs27-source
@@ -0,0 +1 @@
+/nix/store/s7bvgynzfisna3jdq2cr4jx73xnhxs27-source
diff --git a/.direnv/flake-inputs/yj1wxm9hh8610iyzqnz75kvs6xl8j3my-source b/.direnv/flake-inputs/yj1wxm9hh8610iyzqnz75kvs6xl8j3my-source
@@ -0,0 +1 @@
+/nix/store/yj1wxm9hh8610iyzqnz75kvs6xl8j3my-source
diff --git a/.direnv/flake-profile-a5d5b61aa8a61b7d9d765e1daf971a9a578f1cfa b/.direnv/flake-profile-a5d5b61aa8a61b7d9d765e1daf971a9a578f1cfa
@@ -0,0 +1 @@
+/nix/store/9si7pq5zfzmhrqax0fayiwdamnr9yl49-nix-shell-env
diff --git a/.direnv/flake-profile-a5d5b61aa8a61b7d9d765e1daf971a9a578f1cfa.rc b/.direnv/flake-profile-a5d5b61aa8a61b7d9d765e1daf971a9a578f1cfa.rc
diff --git a/examples/Cargo.toml b/examples/Cargo.toml
@@ -8,6 +8,7 @@ members = [
     "colors_rgb",
     "demo",
     "demo2",
+    "hyperlinks",
     "minimal",
     "pong",
     "shared",
diff --git a/examples/hyperlinks/Cargo.toml b/examples/hyperlinks/Cargo.toml
@@ -0,0 +1,9 @@
+[package]
+name = "hyperlinks"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[dependencies]
+ratzilla.workspace = true
+console_error_panic_hook.workspace = true
diff --git a/examples/hyperlinks/index.html b/examples/hyperlinks/index.html
@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no"
+    />
+    <link
+      rel="stylesheet"
+      href="https://cdnjs.cloudflare.com/ajax/libs/firacode/6.2.0/fira_code.min.css"
+    />
+    <title>Ratzilla Hyperlinks</title>
+    <style>
+      body {
+        margin: 0;
+        width: 100%;
+        height: 100vh;
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+        align-content: center;
+        background-color: #121212;
+      }
+
+      pre {
+        font-family: "Fira Code", monospace;
+        font-size: 16px;
+        margin: 0;
+      }
+    </style>
+  </head>
+  <body></body>
+</html>
diff --git a/examples/hyperlinks/src/main.rs b/examples/hyperlinks/src/main.rs
@@ -0,0 +1,92 @@
+use std::io;
+
+use ratzilla::{
+    ratatui::{
+        layout::{Alignment, Constraint, Layout, Rect},
+        prelude::{Color, Stylize, Terminal},
+        widgets::{Block, BorderType, Clear, Paragraph},
+    },
+    widgets::Hyperlink,
+    DomBackend, WebRenderer,
+};
+
+fn main() -> io::Result<()> {
+    std::panic::set_hook(Box::new(console_error_panic_hook::hook));
+
+    let terminal = Terminal::new(DomBackend::new()?)?;
+    terminal.draw_web(|frame| {
+        frame.render_widget(Clear, frame.area());
+
+        let [card] = Layout::vertical([Constraint::Length(9)])
+            .flex(ratzilla::ratatui::layout::Flex::Center)
+            .areas(frame.area());
+        let [card] = Layout::horizontal([Constraint::Length(44)])
+            .flex(ratzilla::ratatui::layout::Flex::Center)
+            .areas(card);
+
+        frame.render_widget(
+            Block::bordered()
+                .border_type(BorderType::Rounded)
+                .title(" Aliasable Hyperlinks ".bold())
+                .border_style(Color::LightGreen),
+            card,
+        );
+
+        let inner = card.inner(ratzilla::ratatui::layout::Margin {
+            vertical: 1,
+            horizontal: 2,
+        });
+        let [intro, docs, repo, plain] = Layout::vertical([
+            Constraint::Length(2),
+            Constraint::Length(1),
+            Constraint::Length(1),
+            Constraint::Length(1),
+        ])
+        .spacing(0)
+        .areas(inner);
+
+        frame.render_widget(
+            Paragraph::new("DOM links use native browser anchors.")
+                .alignment(Alignment::Left),
+            intro,
+        );
+        render_link(
+            frame,
+            docs,
+            "Docs: ",
+            Hyperlink::with_label(
+                "Ratatui rendering guide".black().on_cyan().bold(),
+                "https://ratatui.rs/concepts/rendering/under-the-hood/",
+            ),
+        );
+        render_link(
+            frame,
+            repo,
+            "Repo: ",
+            Hyperlink::with_label(
+                "ratzilla on GitHub".black().on_yellow().italic(),
+                "https://github.com/ratatui/ratzilla",
+            ),
+        );
+        render_link(
+            frame,
+            plain,
+            "Website: ",
+            Hyperlink::new("https://ratatui.rs".light_cyan().underlined()),
+        );
+    });
+    Ok(())
+}
+
+fn render_link(
+    frame: &mut ratzilla::ratatui::Frame<'_>,
+    area: Rect,
+    label: &str,
+    link: Hyperlink<'_>,
+) {
+    let [prefix, suffix] =
+        Layout::horizontal([Constraint::Length(label.len() as u16), Constraint::Min(0)])
+            .areas(area);
+    frame.render_widget(Paragraph::new(label), prefix);
+    frame.render_widget(link, suffix);
+}
diff --git a/src/backend/dom.rs b/src/backend/dom.rs
@@ -25,6 +25,7 @@ use crate::{
     error::Error,
     event::{KeyEvent, MouseEvent},
     render::WebEventHandler,
+    widgets::hyperlink_state,
     CursorShape,
 };
 
@@ -78,6 +79,10 @@ pub struct DomBackend {
     initialized: Rc<RefCell<bool>>,
     /// Cells.
     cells: Vec<Element>,
+    /// Current cell contents.
+    buffer: Vec<Cell>,
+    /// Current hyperlink targets for each cell.
+    hyperlinks: Vec<Option<std::rc::Rc<str>>>,
     /// Grid element.
     grid: Element,
     /// The parent of the grid element.
@@ -162,6 +167,8 @@ impl DomBackend {
         let mut backend = Self {
             initialized,
             cells: vec![],
+            buffer: vec![],
+            hyperlinks: vec![],
             grid: document.create_element("div")?,
             grid_parent,
             options,
@@ -225,6 +232,23 @@ impl DomBackend {
         Size::new((w / cell_size.0) as u16, (h / cell_size.1) as u16)
     }
 
+    fn render_cell(&self, index: usize) -> Result<(), Error> {
+        let cell = &self.buffer[index];
+        let elem = &self.cells[index];
+
+        elem.set_inner_html("");
+        elem.set_attribute("style", &get_cell_style_as_css(cell))?;
+
+        if let Some(url) = &self.hyperlinks[index] {
+            let anchor = create_anchor(&self.document, cell.symbol(), url)?;
+            elem.append_child(&anchor)?;
+        } else {
+            elem.set_inner_html(cell.symbol());
+        }
+
+        Ok(())
+    }
+
     /// Resize event types.
     const RESIZE_EVENT_TYPES: &[&str] = &["resize"];
 
@@ -233,6 +257,8 @@ impl DomBackend {
         self.grid = self.document.create_element("div")?;
         self.grid.set_attribute("id", &self.options.grid_id())?;
         self.cells.clear();
+        self.buffer.clear();
+        self.hyperlinks.clear();
         Ok(())
     }
 
@@ -244,8 +270,11 @@ impl DomBackend {
         for _y in 0..self.size.height {
             let mut line_cells: Vec<Element> = Vec::new();
             for _x in 0..self.size.width {
-                let span = create_span(&self.document, &Cell::default())?;
+                let cell = Cell::default();
+                let span = create_span(&self.document, &cell)?;
                 self.cells.push(span.clone());
+                self.buffer.push(cell);
+                self.hyperlinks.push(None);
                 line_cells.push(span);
             }
 
@@ -316,26 +345,51 @@ impl Backend for DomBackend {
             self.populate()?;
         }
 
+        let mut dirty_cells = vec![false; self.cells.len()];
+
         for (x, y, cell) in content {
             let cell_position = (y * self.size.width + x) as usize;
-            let elem = &self.cells[cell_position];
-
-            elem.set_inner_html(cell.symbol());
-            elem.set_attribute("style", &get_cell_style_as_css(cell))
-                .map_err(Error::from)?;
+            self.buffer[cell_position] = cell.clone();
+            dirty_cells[cell_position] = true;
 
             // don't display the next cell if a fullwidth glyph preceeds it
             if cell.symbol().len() > 1 && cell.symbol().width() == 2 {
                 if (cell_position + 1) < self.cells.len() {
-                    let next_elem = &self.cells[cell_position + 1];
-                    next_elem.set_inner_html("");
-                    next_elem
-                        .set_attribute("style", &get_cell_style_as_css(&Cell::new("")))
-                        .map_err(Error::from)?;
+                    self.buffer[cell_position + 1] = Cell::new("");
+                    dirty_cells[cell_position + 1] = true;
                 }
             }
         }
 
+        let mut next_hyperlinks = vec![None; self.cells.len()];
+        for region in hyperlink_state::take() {
+            let row_offset = region.y as usize * self.size.width as usize;
+            if row_offset >= next_hyperlinks.len() {
+                continue;
+            }
+            let start = row_offset + region.x as usize;
+            if start >= next_hyperlinks.len() {
+                continue;
+            }
+            let end = (start + region.width as usize).min(row_offset + self.size.width as usize);
+            for cell in &mut next_hyperlinks[start..end] {
+                *cell = Some(region.url.clone());
+            }
+        }
+
+        for (index, current) in next_hyperlinks.iter().enumerate() {
+            if self.hyperlinks[index].as_deref() != current.as_deref() {
+                dirty_cells[index] = true;
+            }
+        }
+        self.hyperlinks = next_hyperlinks;
+
+        for (index, dirty) in dirty_cells.into_iter().enumerate() {
+            if dirty {
+                self.render_cell(index)?;
+            }
+        }
+
         Ok(())
     }
 
@@ -396,6 +450,15 @@ impl Backend for DomBackend {
     }
 
     fn clear(&mut self) -> IoResult<()> {
+        for cell in &mut self.buffer {
+            *cell = Cell::default();
+        }
+        for link in &mut self.hyperlinks {
+            *link = None;
+        }
+        for index in 0..self.cells.len() {
+            self.render_cell(index)?;
+        }
         Ok(())
     }
 
diff --git a/src/backend/mod.rs b/src/backend/mod.rs
@@ -22,7 +22,7 @@
 //! |------------------------------|------------|---------------|----------------|
 //! | **60fps on large terminals** | ✗          | ✗             | ✓              |
 //! | **Memory Usage**             | Highest    | Medium        | Lowest         |
-//! | **Hyperlinks**               | ✗          | ✗             | ✓              |
+//! | **Hyperlinks**               | ✓          | ✗             | ✓              |
 //! | **Text Selection**           | Linear     | ✗             | Linear/Block   |
 //! | **Unicode/Emoji Support**    | Full       | Limited²      | Full¹          |
 //! | **Dynamic Characters**       | ✓          | ✓             | ✓¹             |
diff --git a/src/backend/utils.rs b/src/backend/utils.rs
@@ -30,15 +30,12 @@ pub(crate) fn create_span(document: &Document, cell: &Cell) -> Result<Element, E
     Ok(span)
 }
 
-/// Creates a new `<a>` element with the given cells.
-#[allow(dead_code)]
-pub(crate) fn create_anchor(document: &Document, cells: &[Cell]) -> Result<Element, Error> {
+/// Creates a new `<a>` element with the given symbol and URL.
+pub(crate) fn create_anchor(document: &Document, symbol: &str, url: &str) -> Result<Element, Error> {
     let anchor = document.create_element("a")?;
-    anchor.set_attribute(
-        "href",
-        &cells.iter().map(|c| c.symbol()).collect::<String>(),
-    )?;
-    anchor.set_attribute("style", &get_cell_style_as_css(&cells[0]))?;
+    anchor.set_attribute("href", url)?;
+    anchor.set_inner_html(symbol);
+    anchor.set_attribute("style", "color: inherit; text-decoration: inherit;")?;
     Ok(anchor)
 }
 
diff --git a/src/render.rs b/src/render.rs
@@ -5,6 +5,7 @@ use web_sys::{wasm_bindgen::prelude::*, window};
 use crate::{
     error::Error,
     event::{KeyEvent, MouseEvent},
+    widgets::hyperlink_state,
 };
 
 /// Trait for rendering on the web.
@@ -72,6 +73,7 @@ where
         *callback.borrow_mut() = Some(Closure::wrap(Box::new({
             let cb = callback.clone();
             move || {
+                hyperlink_state::begin_frame();
                 self.draw(|frame| {
                     render_callback(frame);
                 })
diff --git a/src/widgets/hyperlink.rs b/src/widgets/hyperlink.rs
diff --git a/src/widgets/hyperlink_state.rs b/src/widgets/hyperlink_state.rs
diff --git a/src/widgets/mod.rs b/src/widgets/mod.rs

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/nix/store/01x5k4nlxcpyd85nnr0b9gm89rm8ff4x-source`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/nix/store/0d3h8gi2q46fb4l563h6pginjw2a90r4-source`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/nix/store/4f3q0m4zz7k7si8cga2bwvj3x194zygp-source`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/nix/store/lvh1shxv1jhm7iacffl2iliyza2pfmn0-source`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/nix/store/s7bvgynzfisna3jdq2cr4jx73xnhxs27-source`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/nix/store/yj1wxm9hh8610iyzqnz75kvs6xl8j3my-source`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+/nix/store/9si7pq5zfzmhrqax0fayiwdamnr9yl49-nix-shell-env`