New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
0.2.0 API Redesign #10
Comments
@creativecreatorormaybenot Please let me know your thoughts on this design. They are heavily inspired by your CaTeX project and you are of course more experienced on this subject. |
@znjameswu Thanks for pinging me - I will take a look probably on Tuesday; until then I am busy, but I will not forgot to take a look. It looks very exciting 🔥 |
|
@znjameswu Yes, certainly. I actually have no objections to verbose variable names (e.g. I know I said Tuesday, but I think by this week is a better estimate - so I will get back by Sunday for sure; preferably earlier :) |
Thanks for your comment. No need to hurry! Right now I only finished a The internal implementation on the master branch has already been changed to using |
Here are some of my thoughts:
I like the idea for the development side of the API. In terms of usage, I feel like it would be nice to have one widget (at least for view-only and selectable). For example, Flutter has Furthermore, I am not sure if
I think that a single import should be provided for normal API use because it is cumbersome having to import two libraries for using one widget. More precisely, when I want to use a Moreover, I think that a library export is idiomatic. So maybe you want to have a library export that just redirects to ConclusionI really like these changes 🔥 and I am already really excited to see them in action 🚀 NoteI already took a look at some of the commits you pushed - maybe a little bit of advice here: it does make sense to not push every commit to |
Thanks for your comments. They are very inspiring. Widget separationYes, I also thought about flipping the name. But I can't find a proper name for a static, non-selectable widget. A non-selectable widget is kind of important, because its implememtation was designed to avoid any state management cost, while selectable ones shares the same performance penalty as the editable. I think I think editable widget can take the parameter to controll modes and probably change modes internally. Library exportsI will follow your advice. A main export containing all frequently used utilities and other exports for less frequently used ones. Commit styleI must apologize for the makeshift style of commits on master. As the majority of the work has finished, I'll take a better style of commit management.😅 |
Progress UpdateSelectable WidgetWith commit 95410f6, selectibility-related feature is about to complete. The only blocking issue is this DDC bug flutter/flutter#66122 causing severe, undebuggable runtime error during web debugging on (currently) all Flutter channels. This is due to the code patterns used in implementing selectable widgets (mixin pattern to be specific, which I am reluctant to refactor for a compiler bug). I think it's best to hold off until this bug is solved by Flutter's cherrypick. Features already finished:
Features yet to be completed
EncoderThe encoder now support the encoding of some most frequently used node types. The output will be imprecise in a lot of cases, but it is optimized and concise. New APIAfter some coding, I find your suggestion of naming to be better after all @creativecreatorormaybenot 😄. |
@znjameswu The selection feature is really impressive 👌 🚀 And I know the pain - I have also struggled with DDC issues a lot in the past year; really looking forward to web becoming stable. What is the hack for right click to copy? Are you talking about the fact that Flutter does not support regular context menus on web? Regarding the naming, I think that given how some framework widgets are named, |
I see: you used a |
Sure, For equations, the |
@znjameswu That is very interesting thanks 👌 |
0.2.0 has been released. Though dartdoc is currently broken at pub.dev dart-lang/pub-dev#4166 |
@znjameswu Awesome news 🚀 |
@znjameswu I forgot to send the comment: I tried the new release and I think it works awesome. I really appreciate the new project structure, Git workflow, and naming 👌 It seems like there are still some problems with |
@creativecreatorormaybenot I agree that the selection part is very rough and unpolished. I initially thought it would be easy to just copy from Flutter's built-in widgets, but later found Flutter's implementation to be rough as well. My current plan is to halt feature development, as selection and IME handling problems are still hard to tackle at now, and wait for Flutter team to come up with nicer solutions. But I will still do the NNBD migration and bugfixes. Again thank you for your interest in this work! |
How about |
Current 0.1.x's API design is more of a makeshift design that has a lot of oversight and redundancy which is later proved to be not so useful. As the development for follow-up feature goes deeper and I'm having a better understanding for the API demand, it is probably the time to stablize the API and make some unavoidable breakings. The proposed API change takes inspirations from other projects from zefyr and CaTeX.
Widget variants
The first part is to break up widgets into
MathView
,MathSelectable
, and (future)MathEditable
, instead of oneFlutterMath
. This will avoid extra performance cost and API surface when onlyMathView
is needed.FlutterMath
will be deprecated and then removed.TextStyle over Options
TextStyle
will be adopted as the parameter in exposed APIs to replaceOptions
. This will have several implications:TextStyle.fontSize
will be the logical pixel count of 1cssEm
(which is thefontSize
passed to Text widget underMathStyle.display
and normal size). This will affect all relative length units such asmu
, etc. A constantdefaultMathFontSize
will be provided.lpPerInch
will be used to decide the length of absolute units. IflpPerInch
is null, then absolute units will follow relative units and resize on differentTextStyle.fontSize
(Just like currentbaseSizeMultiplier
's behavior). A functiondouble defaultLpPerInch(double fontSize)
will be provided to calculate the effectivelpPerInch
when set to null.baseSizeMultiplier
will be removed.The final API will look like
Renaming classes
Some old classnames are prone to naming collision in user code. The following will be an incomplete list of renaming:
Options
->MathOptions
Settings
->TexSettings
SizeMode
->MathSize
Grouping exports
Now exports will be grouped into three libraries
package:flutter_math/widgets.dart
exports basic widgetspackage:flutter_math/ast.dart
exports AST nodes and necessary toolingpackage:flutter_math/tex.dart
exports TeX parser and useful settingsUpdating Plan
Aside from the variant widget proposal, all other changes are breaking.
Currently
MathSelectable
and a bunch of optimizations is in the works. Widget variants,MathSelectable
and those optimizations will land in 0.1.9. 0.1.9 will also markFlutterMath
as deprecated. However, none of these will be breaking.After 0.1.9 is rolled, 0.2.0 will come out very shortly, with all the above breaking changes. 0.2.0 will also remove
FlutterMath
.The text was updated successfully, but these errors were encountered: