ink: Support `Box` overflow and scrolling
Firstly: this library is amazing; I’m so excited to use it everywhere I possibly can. Sadly, this issue describes a use case that’s blocking me from moving forward 😦
I’m opening this issue and offering a corresponding Gitcoin bounty in hopes it will help. Thank you to anyone who can help make this happen!
Summary
This feature request seeks to cover the use case where a component may exceed the bounds of its container. Specifically, this issue seeks the following behaviors:
- Allow
<Box overflow={...}>, perhaps as implemented by #393 - Allow Box components to scroll their contents. Based on my research, #393 alone is insufficient, since it doesn’t provide a way for a component to measure what its full width/height would be. (When
overflow="hidden"is provided, width/height are measured based on the final component on-screen, and there seems to be no way around this)
Related
PR #393 (Add overflow prop to Box component) is mostly complete for my concerns here. I outlined my concerns with scrolling / measurements in this comment, but no idea what the right answer is.
https://github.com/vadimdemedes/goodness-squad/issues/5 describes a related use case (Fullscreen UIs). This issue doesn’t target fullscreen UIs specifically; overflow/scrolling behavior should work regardless of whether the component is going to be fullscreen or not.
Acceptance criteria
See comment below
Notes
Please let me know if the requirements could use clarification! I’m very keen to get this working 🙇
About this issue
- Original URL
- State: closed
- Created 6 years ago
- Reactions: 2
- Comments: 27 (4 by maintainers)
Commits related to this issue
- solution https://github.com/vadimdemedes/ink/issues/432 — committed to developerfred/ink-box-upgrade by developerfred 6 years ago
- Update code to match vadimdemedes's example see https://github.com/vadimdemedes/ink/issues/432#issuecomment-1519671092 — committed to gnidan/ink-scroller by gnidan 4 years ago
I think it would be interesting to have that as a separate npm package, but I’m not sure I’d want to have that in Ink itself. If you have a complicated CLI that requires scrolling areas, you might be better of with ncurses-based alternative like blessed.
@vadimdemedes I remember from my exploration into this issue that we can’t get a separate NPM package to work without a change to Ink’s rendering methods… since Ink is responsible for doing all the layout math, it needs to keep track of the “full size” dimensions as well as the computed dimensions on-screen (what I call “natural size” vs. “fixed size” above), but the problem is that there’s no way (right now) to create a react hook to report the natural size dimensions. It looks like this information gets lost somewhere deep inside the renderer (or worse, inside the Yoga/flexbox computations).
This stuff is all very confusing to me, however, since Yoga doesn’t (didn’t?) have good API documentation. Maybe I’m wrong.
@developerfred is this still current? It seems rather barebones, and it doesn’t currently even run at all (looks like you have a syntax error).
Anyway, I notice there is some movement on #412 and also I see #472 is new since I’ve spent effort investigating the state of this issue. @vadimdemedes could you please comment on what a path forward might look like? I’m fine if it is actually possible to achieve this “natural size” calculation in a separate NPM package, but I just don’t see how that’s possible.
If further coordination across existing PRs is necessary, I could potentially double the bounty and split it up across contributors/maintainers, since I really want this behavior, but mind you I’m only working with my personal funds here. But if this is a multi-person effort, I do want to recognize that and reward everyone’s efforts. This behavior is the only thing stopping me from using Ink for a number of projects of varying sizes, and I can’t move forward on those projects in a way that satisfies me (because, well, who wants to use blessed when ink exists 😉
The issue with blessed and similar variants is we don’t get the declarative dom-like environment that we get here… as it stands and (please someone correct me if I’m wrong), Ink is the only project that makes building a CLI or TUI more or less like building for the web…
And I believe that’s hugely important because we’ve come to realize the terminal offers one of the most productive, distraction free environments in existence… a turn-key solution to scrolling is absolutely fundamental in my opinion. Thanks for listening
Thanks @gnidan, every dollar makes the Ukrainian victory closer 💛
Awesome @developerfred, glad to hear about progress!
In the meantime, I grabbed the relevant stuff from my use case and made a repo for it at gnidan/ink-scroller. There’s something strange going on with left/right scrolling, but I’m less focused on that, since I just haven’t looked into it.
Point of that repo: I want to be able to stop scrolling at the end of the text 😃
Acceptance criteria
A1. Given component A of unknown “natural size” (xA, yA) inside parent component B of fixed size (xB, yB),
A1.1. A must render within the bounds of B with overflow hidden
A1.2. Either A or B must be able to compute A’s natural size (xA, yA), e.g. to ensure that A never completely leaves the viewport of B.
A2. Solutions must perform reasonably well without noticeable re-rendering or other flickering. This might mean fixing the flickering described in https://github.com/vadimdemedes/ink/issues/359, but not necessarily (since A1 paired with stdout measurement means it’d be trivial to prevent rendering something larger than the terminal).
A3. Solutions must work with existing components in the ecosystem, including ink-spinner, ink-select-input, ink-progress-bar, etc. This means one of two options:
A3 (option 1, strongly preferred). Solution is merged and released as part of this library’s official distribution channel. This means getting @vadimdemedes’s approval, but I don’t want to rely on that for this bounty.
A3 (option 2). Solution is releasable as a forked NPM package. Two stipulations:
A3(2).1. Changes are opened as PR here (so that I may seek to champion getting the changes into a main-line release once your work is done)
A3(2).2. Solution includes clear instructions on getting the above-mentioned component packages to work cleanly. Those packages use
"ink"itself as a dependency inpackage.json, and that means ink-spinner (e.g.) will try to use the officially-released rendering logic as opposed to whatever modified version your solution provides. (I ran into this problem when I released #393 as a fork.) Solutions that require forking any/all component packages are not acceptable, and my use case doesn’t afford leveraging systems like yarn’sresolutionsconfig. (I intend to use this work in a dependent application released to NPM and installable withnpm install, so yarn-specific niceties are sadly just not going to cut it.)A4. Solution includes automated tests and follows consistent style and quality alongside the rest of Ink’s codebase.
This is about the extent of what I can think of as necessary, but of course I understand that there may be ambiguity or technical limitations when it comes to the details. Please don’t hesitate to communicate any comments, questions, or concerns.
Thank you to everyone who has thus far applied to work on this bounty! I will continue reviewing each of your applications and will respond to each individually in the next 48 hours. ❤️
The solution works well and I’d like to thank you all for the nice work. Made it easy for me.
Just for future readers: If you’re looking for a typescript version that can re-scale based on resize events, see https://gist.github.com/Carnageous/1a55a8747f12e1c4fc86ebe2d05a0a55
Combine that with
useStdoutDimensionsand it works very well!Regarding the bounty portion of this issue, I consider the matter resolved. I can use the regular
"ink"NPM package to get<Box />with both overflow support and support for bounded scrolling, which is exactly what I have needed!With pleasure, I’d like to remit the 1 ETH funds associated with this bounty.
@developerfred: Although your solution did not meet acceptance criteria, ~I’m sending you a 0.1 ETH tip for your attempt when I first opened this. You’re already in the Gitcoin system, so I was able to use the Gitcoin webapp UI to issue this payout… unfortunately I didn’t check the gas price, so that transaction may get dropped. Don’t worry; I will monitor this and make sure you get paid.~ Edit: I sent you the 0.1 ETH here. Thank you!
@tin-t: I’d like to offer you a 0.2 ETH tip as gratitude for your work on the initial implementation of
<Box overflow />support in #393.@vadimdemedes: Between #502 and https://github.com/vadimdemedes/ink/issues/432#issuecomment-1519671092, your work clearly meets the acceptance criteria, and thus you deserve the 1.0 ETH! I would like to send this to you.
But, for both @tin-t and @vadimdemedes… I don’t know how to issue you these payments.
and associated with this bounty(edit: this last part doesn’t matter… I can send a tip to any Gitcoin account, it seems).I understand that the two of you might not be prepared to receive ETH. I apologize if this is the case, but unfortunately (for budgeting and tax reasons), I can’t issue the payout in a different currency other than ETH. I am happy to walk you through the process of making an Ethereum account and helping you find a reputable fiat off-ramp that you can use if you want to convert the funds into your local currencies. Please let me know.
For housekeeping purposes, I’ll plan to leave both this GH issue and the associated bounty open until it’s fully paid. I worry that something on the Gitcoin side will break otherwise…
Anyway, thank you everyone who contributed to this issue, and enormous thanks to you @vadimdemedes for all your work on Ink, really 😃. I’m looking forward to picking up where I left off when I first got blocked by this overflow/scrolling thing.
Cheers all!
Edit: @vadimdemedes it looks like you might already have a Gitcoin account? But no Ethereum address associated, so I’ll still wait to hear from you.
Now that
Boxsupportsoverflow="hidden", it’s possible to create a scrollable box without modifying Ink internals.Here’s an example
ScrollAreacomponent I created for scrolling vertically positioned items:Usage:
https://user-images.githubusercontent.com/697676/233948081-0d1823a4-9af6-4785-a38d-fe7b4c4b3721.mp4
I think a similar component can be made to support horizontally scrollable items as well.
The problem I didn’t account here is focus management.
ScrollArealistens to arrow up/down keys viauseInput, so if we were to also render aSelectInputat the same time, which also listens to the same keys, both of these components would react to them.ScrollAreawould scroll andSelectInputwould select a different item.We could make
ScrollAreaa focusable component by usinguseFocus, so it’d only scroll the items ifScrollAreais focused.However, this wouldn’t work properly if we rendered a
ScrollAreawithTextInput, which is also a focusable component, but it doesn’t listen to arrow up or arrow down keys. So ifTextInputwas placed inside aScrollAreaand would be focused, pressing arrow up/down keys wouldn’t scroll theScrollArea.One of the options would be to explicitly document that
ScrollAreais supposed to scroll non-focusable elements. Another option would be to have an independent focus management forScrollAreacomponents, separate fromuseFocusanduseFocusManagerthat’s used by user-land components.Thinking out loud. Let me know your thoughts on this.
Glad to see some activity on this issue. I’ll review the acceptance criteria and state of current efforts. I still want this, and I’m still willing to spend the listed bounty!
Thanks for your insight @vadimdemedes and @zach-is-my-name 🙏
Hi @gitcoinbot my code will be here https://replit.com/@codingsh/poc-ink-box-upgrade