Blender's GPU Accelerated UI, Decoupled from it's original codebase. Supports Rust, Python, JS, React, C & C++. Twice as good as GPUI
//! A virtual list in shadcn's component style, with TanStack Virtual's names.
//! shadcn/ui has no virtual list, so this follows `@tanstack/react-virtual`:
//!
//! | TanStack Virtual | here |
//! |---|---|
//! | `count` | `count` ([`VirtualList`]); a [`ChatList`] has its `messages` |
//! | `estimateSize` | `estimate_size` (px of a one-line item before it is measured) |
//! | `overscan` | `overscan` (items beyond the viewport the source is asked for) |
//! | `getItemKey` | `get_item_key` (ascending keys) |
//! | `scrollToIndex(index, { align })` | [`ListHandle::scroll_to_index`] |
//! | `scrollToOffset(offset)` | [`ListHandle::scroll_to_offset`] |
//! | `measureElement` | [`ListHandle::measure_element`] (a height you know) |
//! | `onChange` / `range` | `on_range_change`, [`ListHandle::range`] |
//! | `getTotalSize()`, `scrollOffset` | [`ListHandle::view_info`] |
//!
//! The rows are not elements: the engine draws visible rows' wrapped text
//! straight from the source ([`blenderui_vlist`]), so a list of ten million
//! items costs what a screenful does. An item is therefore text
//! (`item(index, out)` writes it), not JSX.
use std::rc::Rc;
use std::sync::Arc;
pub use blenderui_vlist::{Align, Message};
pub use crate::vlist::ViewInfo;
use blenderui_vlist::{ChatList as ChatCore, CountSource, ItemSource, List, Options, RowList, RowStyle};
use crate::css::Decl;
use crate::hooks::{use_signal, Complete, Signal};
use crate::prelude::*;
use crate::vlist::{chat_list, theme_palette, variable_list, ListState};
/// Writes the text of item `index` into the buffer (`item`).
pub type ItemText = Box<dyn Fn(usize, &mut String)>;
/// A change to make to a list (what `scrollToIndex` and friends send).
#[derive(Clone, Debug, PartialEq)]
pub enum ListCommand {
ScrollToIndex(usize, Align),
ScrollToOffset(f64),
ScrollToEnd,
/// A height in px that is known for sure (`measureElement`).
MeasureElement(usize, f64),
/// A new message at the end ([`ChatList`] only).
Push(Message),
/// Replace the text of message `n` ([`ChatList`] only).
Edit(usize, String),
/// The items changed without the count changing: measure again.
Invalidate,
}
/// A list the commands apply to.
trait Drive {
fn apply(&mut self, cmd: ListCommand);
}
fn common<S: ItemSource, P: blenderui_vlist::Measurer + blenderui_vlist::ItemPainter + Clone>(list: &mut List<S, P>, cmd: ListCommand) {
match cmd {
ListCommand::ScrollToIndex(i, align) => list.view.jump_to(i, align),
ListCommand::ScrollToOffset(px) => list.view.scroll_to_offset(px),
ListCommand::ScrollToEnd => list.view.scroll_to_end(),
ListCommand::MeasureElement(i, px) => list.view.set_known_height(i, px),
ListCommand::Invalidate => {
let style = list.style.clone();
list.restyle(style);
}
ListCommand::Push(_) | ListCommand::Edit(..) => {}
}
}
impl Drive for RowList {
fn apply(&mut self, cmd: ListCommand) {
common(self, cmd);
}
}
impl Drive for ChatCore {
fn apply(&mut self, cmd: ListCommand) {
match cmd {
ListCommand::Push(m) => self.push(m),
ListCommand::Edit(i, text) => self.edit(i, &text),
other => common(self, other),
}
}
}
/// The list behind a handle.
trait ListOps {
fn run(&self, cmd: ListCommand, cx: &mut App);
fn info(&self, cx: &App) -> ViewInfo;
}
struct ListLink<S: ItemSource + 'static, P: blenderui_vlist::Measurer + blenderui_vlist::ItemPainter + 'static> {
state: Entity<ListState<S, P>>,
}
impl<S: ItemSource + 'static, P: blenderui_vlist::Measurer + blenderui_vlist::ItemPainter + 'static> ListOps for ListLink<S, P>
where
List<S, P>: Drive,
{
fn run(&self, cmd: ListCommand, cx: &mut App) {
self.state.update(cx, |s, _| s.apply(cmd));
}
fn info(&self, cx: &App) -> ViewInfo {
self.state.read(cx).view_info()
}
}
/// `useVirtualizer`'s result: a `Copy` handle to a list.
///
/// ```ignore
/// let list = use_virtual_list();
/// rsx! { <VirtualList list={list} count={1_000_000} item={|i: usize, out: &mut String| out.push_str(&i.to_string())} /> }
/// // in a handler:
/// list.scroll_to_index(500, Align::Center, cx);
/// ```
#[derive(Clone, Copy)]
pub struct ListHandle {
view: Signal<ViewInfo>,
ops: Signal<Option<Rc<dyn ListOps>>>,
}
/// A list handle for the calling component (the same one on every render).
#[track_caller]
#[must_use]
pub fn use_virtual_list() -> ListHandle {
ListHandle { view: use_signal(ViewInfo::default()), ops: use_signal(None) }
}
impl ListHandle {
/// Send `cmd` to the list (nothing happens before its first frame).
pub fn dispatch(self, cmd: ListCommand, cx: &mut App) {
if let Some(ops) = self.ops.get() {
ops.run(cmd, cx);
cx.notify_all();
}
}
/// `scrollToIndex(index, { align })`.
pub fn scroll_to_index(self, index: usize, align: Align, cx: &mut App) {
self.dispatch(ListCommand::ScrollToIndex(index, align), cx);
}
/// `scrollToOffset(offset)`, px from the top.
pub fn scroll_to_offset(self, offset: f64, cx: &mut App) {
self.dispatch(ListCommand::ScrollToOffset(offset), cx);
}
/// Scroll to the end of the list.
pub fn scroll_to_end(self, cx: &mut App) {
self.dispatch(ListCommand::ScrollToEnd, cx);
}
/// `measureElement`: item `index` is `height` px tall.
pub fn measure_element(self, index: usize, height: f64, cx: &mut App) {
self.dispatch(ListCommand::MeasureElement(index, height), cx);
}
/// Items changed without the count changing: measure again.
pub fn invalidate(self, cx: &mut App) {
self.dispatch(ListCommand::Invalidate, cx);
}
/// A new message at the end of a [`ChatList`].
pub fn push(self, message: Message, cx: &mut App) {
self.dispatch(ListCommand::Push(message), cx);
}
/// The items in the viewport as of the last range change (`range`).
#[must_use]
pub fn range(self) -> std::ops::Range<usize> {
self.view.with(|v| v.range.clone())
}
/// The item count as of the last range change.
#[must_use]
pub fn count(self) -> usize {
self.view.with(|v| v.count)
}
/// The list now: range, count, `scrollOffset` and `getTotalSize()`.
#[must_use]
pub fn view_info(self, cx: &App) -> Option<ViewInfo> {
self.ops.get().map(|o| o.info(cx))
}
}
/// What every list component takes besides its content.
pub struct ListExtras {
base: Div,
handle: Option<ListHandle>,
options: Options,
on_range_change: Option<Rc<dyn Fn(&ViewInfo)>>,
}
impl ListExtras {
fn new() -> Self {
Self { base: div().relative().overflow_hidden().size_full(), handle: None, options: Options::default(), on_range_change: None }
}
}
/// The props every list component shares, written once.
pub trait ListProps: Sized {
#[doc(hidden)]
fn extras_mut(&mut self) -> &mut ListExtras;
/// A handle from [`use_virtual_list`], to scroll and read the list.
#[must_use]
fn list(mut self, handle: ListHandle) -> Self {
self.extras_mut().handle = Some(handle);
self
}
/// `estimateSize`: the height in px an item of one line is assumed to
/// have until it is measured. Read when the list is created.
#[must_use]
fn estimate_size(mut self, px: f32) -> Self {
self.extras_mut().options.estimate_size = Some(px);
self
}
/// `overscan`: items beyond the viewport the source is asked for. Read
/// when the list is created.
#[must_use]
fn overscan(mut self, items: usize) -> Self {
self.extras_mut().options.overscan = items;
self
}
/// `onChange`: the visible range or the count changed.
#[must_use]
fn on_range_change(mut self, f: impl Fn(&ViewInfo) + 'static) -> Self {
self.extras_mut().on_range_change = Some(Rc::new(f));
self
}
/// Stay at the end while new items arrive (the chat default), or not.
#[must_use]
fn stick_to_bottom(mut self, on: bool) -> Self {
self.extras_mut().options.stick_to_bottom = on;
self
}
}
macro_rules! styled_list {
($($ty:ident<$($g:ident),*>)*) => {$(
impl<$($g),*> Styled for $ty<$($g),*> {
fn decls_mut(&mut self) -> &mut Vec<Decl> {
self.extras.base.decls_mut()
}
}
impl<$($g),*> ListProps for $ty<$($g),*> {
fn extras_mut(&mut self) -> &mut ListExtras {
&mut self.extras
}
}
)*};
}
/// A virtualized list of `count` text items (TanStack Virtual's model).
///
/// ```ignore
/// // rsx!
/// rsx! { <VirtualList count={10_000_000} item={|i: usize, out: &mut String| out.push_str("row")} overscan={8} h={px(400.0)} /> }
/// // builder
/// VirtualList::new(10_000_000, |i, out| out.push_str("row")).overscan(8).h(px(400.0))
/// ```
pub struct VirtualList<C = usize, I = ItemText> {
count: C,
item: I,
key: Option<Box<dyn Fn(usize) -> u64>>,
extras: ListExtras,
}
styled_list! { VirtualList<C, I> }
impl VirtualList<(), ()> {
/// `count` items; item `i`'s text is what `item(i, out)` pushes to `out`.
pub fn new(count: usize, item: impl Fn(usize, &mut String) + 'static) -> VirtualList {
Self::__builder().count(count).item(item)
}
#[doc(hidden)]
#[must_use]
pub fn __builder() -> Self {
Self { count: (), item: (), key: None, extras: ListExtras::new() }
}
}
impl<I> VirtualList<(), I> {
/// `count`.
pub fn count(self, count: usize) -> VirtualList<usize, I> {
VirtualList { count, item: self.item, key: self.key, extras: self.extras }
}
}
impl<C> VirtualList<C, ()> {
/// The text of each item: `item(index, out)` pushes it to `out`.
pub fn item(self, item: impl Fn(usize, &mut String) + 'static) -> VirtualList<C, ItemText> {
VirtualList { count: self.count, item: Box::new(item), key: self.key, extras: self.extras }
}
}
impl<C, I> VirtualList<C, I> {
/// `getItemKey`: a stable key per index, ascending with the index.
#[must_use]
pub fn get_item_key(mut self, key: impl Fn(usize) -> u64 + 'static) -> Self {
self.key = Some(Box::new(key));
self
}
}
impl Complete for VirtualList {
type Props = Self;
fn finish(self) -> Self {
self
}
}
type ListSlot<S, P> = Signal<Option<Entity<ListState<S, P>>>>;
/// Publish range changes to the handle and the user's callback.
fn view_changed(handle: ListHandle, user: Option<Rc<dyn Fn(&ViewInfo)>>) -> impl Fn(&ViewInfo) + 'static {
move |info: &ViewInfo| {
if handle.view.with(|v| v != info) {
handle.view.set(info.clone());
}
if let Some(f) = &user {
f(info);
}
}
}
impl IntoElement for VirtualList {
fn into_any_element(self) -> AnyElement {
let Self { count, item, key, extras: ListExtras { base, handle, options, on_range_change } } = self;
let own = use_virtual_list();
let slot: ListSlot<CountSource, RowStyle> = use_signal(None);
let handle = handle.unwrap_or(own);
base.defer(move |_, cx, el| {
let state = match slot.get() {
Some(state) => {
state.update(cx, |s, _| {
let old = s.source.set_count(count);
s.source.set_text(item);
s.source.set_key(key);
let bytes = s.source.avg_bytes();
// an index error cannot happen below 2^40 items
if count > old {
let _ = s.view.appended(count - old, (count - old) as u64 * bytes);
} else if count < old {
s.view.removed(count, old - count, (old - count) as u64 * bytes);
}
});
state
}
None => {
let mut source = CountSource::new(count, item);
source.set_key(key);
let list = List::new(source, RowStyle::new(theme_palette()), 400.0, 300.0, options).expect("a count below 2^40 fits the index");
let state = cx.new(|cx| ListState::new(list, cx));
slot.set(Some(state));
state
}
};
handle.ops.update_quiet(|o| *o = Some(Rc::new(ListLink { state })));
let select = |i: usize, list: &mut RowList| {
let id = list.source.id_at(i);
list.style.selected = if list.style.selected == id { None } else { id };
};
let taken = std::mem::replace(el, Div::new("div"));
*el = taken.child(variable_list(&state).on_item_click(select).on_view_change(view_changed(handle, on_range_change)));
})
.into_any_element()
}
}
/// A chat: a [`VirtualList`] of messages (avatars, runs, day dividers, whole-message
/// selection by click). `messages` is compared by identity: pass the same `Arc`
/// to keep the list, a new one to start another conversation; append with
/// [`ListHandle::push`].
///
/// ```ignore
/// rsx! { <ChatList messages={messages} h={px(400.0)} /> }
/// ChatList::new(messages).h(px(400.0))
/// ```
pub struct ChatList<M = Arc<[Message]>> {
messages: M,
extras: ListExtras,
}
styled_list! { ChatList<M> }
impl ChatList<()> {
/// A chat of `messages`.
pub fn new(messages: impl Into<Arc<[Message]>>) -> ChatList {
Self::__builder().messages(messages)
}
#[doc(hidden)]
#[must_use]
pub fn __builder() -> Self {
let mut extras = ListExtras::new();
extras.options.start_at_end = true;
Self { messages: (), extras }
}
/// `messages`.
pub fn messages(self, messages: impl Into<Arc<[Message]>>) -> ChatList {
ChatList { messages: messages.into(), extras: self.extras }
}
}
impl Complete for ChatList {
type Props = Self;
fn finish(self) -> Self {
self
}
}
impl IntoElement for ChatList {
fn into_any_element(self) -> AnyElement {
let Self { messages, extras: ListExtras { base, handle, options, on_range_change } } = self;
let own = use_virtual_list();
let slot: ListSlot<blenderui_vlist::VecSource, blenderui_vlist::ChatStyle> = use_signal(None);
let shown: Signal<Option<Arc<[Message]>>> = use_signal(None);
let handle = handle.unwrap_or(own);
base.defer(move |_, cx, el| {
let fresh = shown.with(|s| s.as_ref().is_none_or(|s| !Arc::ptr_eq(s, &messages)));
let existing = slot.get().filter(|_| !fresh);
let state = existing.unwrap_or_else(|| {
shown.update_quiet(|s| *s = Some(Arc::clone(&messages)));
let list = ChatCore::from_messages(messages.to_vec(), theme_palette(), 400.0, 300.0, options);
let state = cx.new(|cx| ListState::new(list, cx));
slot.set(Some(state));
state
});
handle.ops.update_quiet(|o| *o = Some(Rc::new(ListLink { state })));
let taken = std::mem::replace(el, Div::new("div"));
*el = taken.child(chat_list(&state).on_view_change(view_changed(handle, on_range_change)));
})
.into_any_element()
}
}