Skip to content

Add a lazy-stack element for long, fast-changing lists - #215

Merged
simonhamp merged 4 commits into
mainfrom
feat/lazy-stack
Nov 19, 2026
Merged

simonhamp merged 4 commits into
mainfrom
feat/lazy-stack

Conversation

@simonhamp

Copy link
Copy Markdown
Member

Adds <native:lazy-stack> (type lazy_stack), a new element for long vertical lists that change often. It's a ScrollView with a LazyVStack, and each child is identified by its node id. native:list is not touched.

SwiftUI's List gets slower with every row inserted into it. On the heimdall firehose (60 new rows a second, capped at 1,000), each List update went from about 10 ms to 250 to 600 ms within a minute. With lazy-stack the same run stayed at 60 fps, and each update took about 5.5 ms on the main thread, flat after the cap. On a real iPhone it stayed smooth all the way through and the scroll position held.

What it supports

  • gap-* between children, plus p-* and bg-* like any element (dark_bg_color too).
  • content-padding, 1 to 4 values like CSS. Server screens send it as contentPadding.
  • shows-indicators.
  • Rows added above the visible ones don't move what you're looking at. If you're at the very top, it stays at the top so the new rows show.

It leaves out separators, swipe actions, pull-to-refresh, row callbacks and auto-scroll. Use native:list when you need those.

The name follows lazy_grid. The Android renderer is in a separate PR stacked on this one. Until that lands, the manifest points Android at the existing ScrollViewRenderer, which ignores content-padding.

Worth checking

  • Not tried in dark mode, with shows-indicators=false, or while scrolling by hand at 60 rows a second.

Tests: 8 new in tests/LazyStackTest.php. The full suite passes (501, 9 skipped).

🤖 Generated with Claude Code

A new element for long feeds that change often. On iOS it is a ScrollView
with a LazyVStack, and each child is identified by its node id.

native:list is a SwiftUI List, and a List gets slower with every row
inserted into it. In the heimdall firehose (60 keyed inserts a second,
capped at 1,000 rows) a List update cost about 10 ms after 100 inserts and
250 to 600 ms once full. The same rows in a lazy stack stayed at about
5.5 ms of main-thread time per update and 60 fps through 3,600 inserts on
the simulator.

It is deliberately small: children, gap-* spacing, the usual padding and
background, a content-padding attribute that pads the scrolled content,
and shows-indicators. No separators, swipe actions, pull-to-refresh,
sections or row callbacks. native:list is unchanged.

A child added above the screen doesn't move what the reader is looking
at: scrollPosition keeps the top child in place. A reader at the very top
is scrolled back to the top so new children show.

Android has no renderer of its own yet. The manifest points it at the
scroll view's renderer, which ignores content-padding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
simonhamp and others added 3 commits November 19, 2026 21:39
Pint reads a docblock line starting with @ as a phpdoc tag, so the
@foreach/@Endforeach in the example tripped phpdoc_separation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* Draw native:lazy-stack with a LazyColumn on Android

Android pointed lazy_stack at the scroll view renderer as a stopgap, which
ignored content-padding. LazyStackRenderer replaces it and matches iOS:

- children are keyed by node id
- gap-* becomes the column's spacing
- p-* and bg-* come in on the modifier like any element
- content_padding_* becomes the LazyColumn's contentPadding
- shows-indicators is accepted but does nothing, since a LazyColumn has
  no scroll indicator

A LazyColumn keeps the first visible child in place by key when children
are added above it, which is right for a reader scrolled down. It does that
at the very top too, so new rows would land above the screen. The renderer
checks during composition, before the new children are measured, whether the
reader was at the top, and if so asks for the top again with
requestScrollToItem(0).

Inside a scroll view the height is unbounded and a LazyColumn would throw,
so it falls back to a plain column, like the lazy grid does.

On an API 35 emulator with the heimdall firehose (60 rows a second, capped
at 1,000), the main thread applied 56 to 60 updates a second for the whole
minute, before and after the cap, with new rows showing at the top. Scrolled
down, the rows on screen stayed put until they were trimmed off the end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Keep Blade directives out of the LazyStack docblock

Pint reads a docblock line starting with @ as a phpdoc tag, so the
@foreach/@Endforeach in the example tripped phpdoc_separation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@simonhamp
simonhamp merged commit 9ad6a11 into main Nov 19, 2026
4 checks passed
@simonhamp
simonhamp deleted the feat/lazy-stack branch November 19, 2026 21:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant