-
-
Notifications
You must be signed in to change notification settings - Fork 129
v2 Roadmap
This document is a work in progress and will get updates until all issues are linked and this disclaimer is removed.
After seeing Beamer well accepted in the community, we are pursuing some new challenges to improve the developer experience and enrich the Beamer ecosystem. Thanks to everyone who contributed to the project so far and I hope to see even more of you in the future!
If you wish to support this work, feel free to upvote and join the Discussion, engage on any related issue or at Beamer Discord, create new issues, open PRs or sponsor this project. See Contributing for more details.
All of the presented changes are open for discussion either here or in their corresponding issues linked below.
(some issues listed are still a placeholder and will be linked when created)
Prerequisites:
- Resolve hanging issues and questions
- Review doc comments and tests
- Clean up and renew the issue board
Supplements:
- Improve and organize examples
- Write article series
- Improve website
Features:
BeamLocationbecomesBeamStack, has finer control over "route structure" and can understand "infinite pushes"- More power to
BeamState; types and notifiers - Rework
BeamGuard - Tab control
- Storage strategies
- Logging with levels
For more details, supplemental work and ideas behind v2, see specific issues or continue reading.
As we crossed 1000 likes on pub and 500 stars on GitHub, the timing feels perfect for new adventures. Big thanks to everyone who has contributed to the project!
Over the past few months, We’ve had some new ideas and have been collecting various experiences from developers and companies using Beamer. Most of it will be documented in this roadmap to v2 that should bring significant improvements and some minor breaking changes. Main focus will be on additional features that should bring even more power to the developer and simultaneously remove the need for somewhat unintuitive workarounds that are currently necessary for certain routing scenarios.
First and foremost, some issues and questions needs to be addressed and entire issue board cleaned up. Before the development of main new features start, I would like to review and cleanup the current state of the package; mostly doc comments and tests.
As a part of this journey, there are a couple of areas of Beamer ecosystem that should also receive care. Most directly related are examples and Beamer website at beamer.dev that should be upgraded and filled with interactive examples.
Over time, we collected a lot of examples from various contributors. We would like to organize them a bit to provide some guided journey from basic to complex ones and signify which use cases they suit best. If some important examples are missing, they will be created so the flow of the "guided journey" is as fluent as possible.
Currently, the website at beamer.dev looks relatively ugly and outdated. It would be great if we could improve the design (help needed) and include all the examples, nested and interactive withing the website. Later, we may also add articles to the website, but this is not in focus at the moment.
I plan to start a Medium series about navigation, covering topics from simple to advanced. I would like to start with basics of vanilla Router API and go from there, eventually using examples with Beamer once we cover how Beamer abstracts the original concepts. Every articles would be composed of 2 articles - the main one and extended version. In the extended version, we'll go deeper into implementation details and expand on core ideas used.
All of the articles will be linked in the Wiki and in project's README.
In no particular order, here we list the most important things that will be worked on. Most of them are not defined fully, which will be done over time. These sections provide high level ideas around certain parts in Beamer, but most of them will be separated into several issues. When a corresponding issues is linked, the main description and ideas will be written there, but we'll keep (and update if needed) the abstract and motivation here.
Some rough estimate for the release of v2 is 1.7.2023. Depending on various factors, mostly contributors and sponsors, this may come sooner.
BeamLocation becomes BeamStack, has finer control over "route structure" and can understand "infinite pushes"
Renaming BeamLocation is something I've been thinking about for years. Most of the people think about word "location" representing a single route. This opinion is also strengthened when we see that RouteInformation has a property called location. In Beamer, BeamLocation was never meant to mean route, but something like "Beam World", i.e. a region in your application that is identifiable by a combination of routes and page stacks. Building a page stack was always the most important part of its functionality, so renaming it to BeamStack should be better. Now the opportunity of v2 makes this breaking change possible so we are going for it. Additionally, we'll add a finer control over route stack so BeamStack makes even more sense.
An interesting problem in declarative routing is being able to handle infinite pushes. If we imagine a shop application that has a product details page. From that page, we can see related products and go to their details page, and so on, inifinitely deep. A natural thing to expect is to have the URI always be /product/:id, but the stack of pages arbitrarily long. This is very challenging to do when we need to declare routes before runtime. There is a workaround that I found and successfully applied in some projects so I want to bring that feature into Beamer internally.
The goal of Router API was to have declarative routing which is guided by state instead of imperative calls. But, in practice, most developers want completely imperative routing and some scenarios require it. Beamer can be used in both ways, where simple imperative API (Beamer.beamTo*) is default, but we have the ability to create our own states whose change will guide the beaming. We will keep the current imperative high-level API, but will rework the internals slightly so the changes on BeamStates guide beaming directly, instead of BeamState being (by default) just a collection of current routing parameters. Another thing that would be nice to have is strong types on the routing parameter, such as being able to declare that the :id in route should be an integer.
BeamGuards are static rules that determine what should happen when we beam somewhere. It is often needed to guard routes that are more easily defined as a complement of some other, smaller, set of routes, instead of listing them all. Then we use guardNonMatching: true which has gained a lot of questions marks from developers when they see it for the first time. We will rework the logic of how guard targets are defined and how guards are applied.
When we "navigate" through tabs within the application, this is not handled by Navigator, but is a navigation event from user's perspective. Currently, to connect parent Beamer with tabs, most often when we have child Beamers within each tab, we would define a listener in both ways and call setState()/Beamer.update(..., rebuild: false). We will try to connect the tab control with Beamer internally which should provide a better developer experience and remove the need for questioning "Am I doing this the right way?".
This is inspired by bottom_navigation_riverpod example where SharedPreferences is used to store the navigation state of each Beamer which then preserves their states if we open the app in a different tab, rebuild the the app by typing the URL, login/logout from the app, etc. We would like to add the storage capability into Beamer directly so we can turn it on/off and access at any time. Developer should also be able to choose their own storage strategy which just needs to implement "BeamerStorage" interface.
It would be useful to have an internal logging solution within Beamer because developers often define their custom logging by specifying a Beamerdelegate.routeListener. The idea is to have internal logging with multiple levels that the developer can easily turn on and off.
Any helpful discussion is beneficial.
If someone would like to take one of the issues on themselves, I’d be happy to assist you in anything you might need. For new ideas, please create a new issue and we could add it to this milestone or some minor release after it, depending on timing, scope and complexity.
Open-source is one of the greatest things there is in software development, but contrary to popular belief, people that maintain these projects do in fact eat, drink and sleep :). If you are interested in supporting this project, you can sponsor it through https://github.com/sponsors/slovnicki or buy me some coffee at https://www.buymeacoffee.com/slovnicki.