In VS we have the concept of elastic content. Part of it is the Expert markers which helps experts speed read to find the solution. The other part are the extra info blocks that can be expanded on demand to explain the content for beginners.
The initial spec was to add one per topic but later it was realised that multiple help texts can be added in between the paragraphs of a topic. We need to be able to collapse and expand any of them
Add API to control the collapse of all blocks.
Create a state to remember which blocks are collapsed by deault.
The collapsible blocks can be create by imitating the code blocks functionality.
The collapsing of blocks should be done via attachments (similar to quick menu, marker attachments). We want to avoid an opinionated recipe. Such that any user can implement any type of collapse they want.
Provide doc, test and demo page.
There's a design proposal in the VS docs under Articles.
VE Blocks - Styled blocks #40
This features aims to provide the ability to render custom boxes for paragraphs including custom icons. this is usually done in books to highlight certain information types. This could also be done with custom embeds, however this solution is sub par since we cannot easily copy paste the info box content or part of it and retain stylings.
VE Blocks - Code block color coding #18
The current implementation of code blocks in Flutter Quill is rather rudimentar. Not much effort was put into this feature so far. We want to develop this feature to render interactive coding tutorials in Visual Space.
Color coding could be done by borrowing the tokens from another open source code editor and applying styling to the lines of text in the renderer without changing the deltas. There are some code editors from where we can borrow the list of tokens. So far I haven't researched a lot the topic. But I imagine a simple and naive implementation would search for language tokens and would apply color coding over them.
Currently the delta format can apply styling over code snippets. The idea itself is rather goofy. Except the benefit of being able to render markers, highlights and attachments using the same logic I'm seeing few reasons why we would allow full formatting in the code. For example now it is possible to add inline code snippet in a code block. Which makes no sense.
At the moment we would be happy with a basic code editor that provides color highlighting. But in the future we plan to add some more basic code editing features such as: syntax error highlighter or jump to token. This is by far not an easy job and I'm not even sure how far we want to go with the inline code or if this could be better done in a custom embed. I'm still thinking if the user interactions make sense.
For example I don't know for sure if selecting part of text and part of a code block should be possible. It's almost like being able to select part of text and part of an image and copy pasting them somewhere else.
Edit
@kthecoder has suggested the possibility of using Microsoft's LSP Protocol to implement autocomplete features. I believe this is somewhat beyond what a text text editor should be doing. Using a library for code editing could be a smarter move, since it's someone else's problem. Someone who specialises in code editing. However at the moment these code editors are mostly abandoned and far from complete. Ex: code_editor
Edit 2
Looks like the authors of this super popular extension for Google Docs are happy with this setup. It appears they don't have access from Google to run automatic color coding at runtime. So therefore they apply styles over the existing text via a wizard that has to be manually triggered. This is insane. No way we are doing this.
Edit 3 - Some questions to consider
How will the code snippets be able to link to git repos? - Via git URL
Could be done, but then there's a major conflict. if the source code changes then the markers go stale. Also mirroring back in the repo incline comments from the code snippets hosted in articles makes also no sense. The best resolution is to keep hidden metadata that links to the git commit. Also we can count on the fact that git commits are mostly immutable (if no force push is used). The idea of automatic mirroring of code changes from repo to article code snippets has more problems than benefits. So we are better keeping a clone of the "mostly immutable" code. Just to prevent accidents. Though there's also major benefit form being able to mirror token renames from source to article. However that mass rename wont be able to safely rename the tokens in plain text. So once again automatic mirroring is a dead end solution. We keep the code snippets inline. Another problem for mirroring would be performance. In the absence of caching we would require a lot of API calls.
How do we integrate comments inline
Using the existing API from VE. Recreating the same features in a different code editor will end up super expensive.
How many codebases do we want to maintain?
Only one if possible.
What happens when copying text that has reactions markers into code snippets?
Ideally we keep the reactions markers there
Do we want autocomplete
Not right away, but on the long term yes. However this is a very complicated problem to deal with. We don't see VS doing code editing as the main editor any time soon.
Do we want collapsible code blocks that render simplified meta-code?
Yes, it's essential for VS tutorials.
Do we want to spend months/years on learning another code editor?
Not really
Do we want a native flutter code editor or a webview?
For performance reasons we want native 100%
Do we trust unmaintained repos, or owners that are absent?
Not at all
Do we want to render multimedia in code?
Yes, for VS tutorials (diagrams, video, etc)
Do we want to reuse the code snippets in other parts of VS?
Yes.
Do we want collaborative code editing?
Yes.
Based on the questions listed above we can conclude we want to have Visual Editor in charge of rendering code blocks. We will disable rich text formatting on the code snippets and leave only code related features (highlights, markers, etc)
VE Blocks - Web, Cursor pointer on link hover #20
Currently the cursor pointer shows only in edit mode when pressing the meta key. In read only mode the pointer arrow is not visible. Also the link should change colors on hover similar to a web link. However this is rather convoluted due to some technical limitations.
Currently flutter does not provide a HoverGestureRegonizer for text. Therefore it's rather difficult to make the link hover work A request to add this feature in Flutter was made a while ago.
The link hover pointer is also not working, though the code looks like it should be working. It works only in edit mode when presing the meta key on Mac. Hover on links does not work even if the behaviour seems to be defined. You can click on it but the pointer does not work.
First I attempted adding a WidgetSpan in the SpanText of the TextLine. However this is not a workable solution. Although it does the job of detecting hover events, the selection no longer works as expected. The whole link gets selected because now it works as an embed.
I think the current best solution is to proceed as in the case of detecting hover for the highlights, by analysing where the pointer lands in the text selection using quills internal utils. This approach keeps the delta document and line rendering code intact while also adding hovering detection capabilities. Currently I'm working to implement this properly for highlights. I'm still facing an issue there. Once ready I will use the same code to solve this issue as well.
Before committing to any particular solution do some of your own research on the subject.
VE Blocks - Unselecting the checkbox does not work
VE Blocks - Headings don't override the size of text #14
This feature was developed in Quill right before the fork. it was purely tested so a lot of quality issues snuck in. Including this one. We can't override the size of sized text with headings. this is standard behaviour in other editors. The last to change the text (font size or heading) has priority in controlling the line height. As you can see the line height changes but not the font size.
For example I checked Google Docs and they have the behaviour as described above. Although in some circumstances even their implementation is rather unreliable. For example if a heading has mixed sizes of text they all scale together until they cant. So if you have a line of text with small fonts and then super large fonts, their implementation wont override the font size. I'm not sure at all if this behaviour even makes sense. I'm eager to hear your thoughts.
VE Blocks - Collapsable text #99
VE Blocks - Styled blocks #40
This features aims to provide the ability to render custom boxes for paragraphs including custom icons. this is usually done in books to highlight certain information types. This could also be done with custom embeds, however this solution is sub par since we cannot easily copy paste the info box content or part of it and retain stylings.
VE Blocks - Code block color coding #18
The current implementation of code blocks in Flutter Quill is rather rudimentar. Not much effort was put into this feature so far. We want to develop this feature to render interactive coding tutorials in Visual Space.
Color coding could be done by borrowing the tokens from another open source code editor and applying styling to the lines of text in the renderer without changing the deltas. There are some code editors from where we can borrow the list of tokens. So far I haven't researched a lot the topic. But I imagine a simple and naive implementation would search for language tokens and would apply color coding over them.
Currently the delta format can apply styling over code snippets. The idea itself is rather goofy. Except the benefit of being able to render markers, highlights and attachments using the same logic I'm seeing few reasons why we would allow full formatting in the code. For example now it is possible to add inline code snippet in a code block. Which makes no sense.
At the moment we would be happy with a basic code editor that provides color highlighting. But in the future we plan to add some more basic code editing features such as: syntax error highlighter or jump to token. This is by far not an easy job and I'm not even sure how far we want to go with the inline code or if this could be better done in a custom embed. I'm still thinking if the user interactions make sense.
For example I don't know for sure if selecting part of text and part of a code block should be possible. It's almost like being able to select part of text and part of an image and copy pasting them somewhere else.
Edit
@kthecoder has suggested the possibility of using Microsoft's LSP Protocol to implement autocomplete features. I believe this is somewhat beyond what a text text editor should be doing. Using a library for code editing could be a smarter move, since it's someone else's problem. Someone who specialises in code editing. However at the moment these code editors are mostly abandoned and far from complete. Ex: code_editor
Edit 2
Looks like the authors of this super popular extension for Google Docs are happy with this setup. It appears they don't have access from Google to run automatic color coding at runtime. So therefore they apply styles over the existing text via a wizard that has to be manually triggered. This is insane. No way we are doing this.
Edit 3 - Some questions to consider
How will the code snippets be able to link to git repos? - Via git URL Could be done, but then there's a major conflict. if the source code changes then the markers go stale. Also mirroring back in the repo incline comments from the code snippets hosted in articles makes also no sense. The best resolution is to keep hidden metadata that links to the git commit. Also we can count on the fact that git commits are mostly immutable (if no force push is used). The idea of automatic mirroring of code changes from repo to article code snippets has more problems than benefits. So we are better keeping a clone of the "mostly immutable" code. Just to prevent accidents. Though there's also major benefit form being able to mirror token renames from source to article. However that mass rename wont be able to safely rename the tokens in plain text. So once again automatic mirroring is a dead end solution. We keep the code snippets inline. Another problem for mirroring would be performance. In the absence of caching we would require a lot of API calls.
How do we integrate comments inline Using the existing API from VE. Recreating the same features in a different code editor will end up super expensive.
How many codebases do we want to maintain? Only one if possible.
What happens when copying text that has reactions markers into code snippets? Ideally we keep the reactions markers there
Do we want autocomplete Not right away, but on the long term yes. However this is a very complicated problem to deal with. We don't see VS doing code editing as the main editor any time soon.
Do we want collapsible code blocks that render simplified meta-code? Yes, it's essential for VS tutorials.
Do we want to spend months/years on learning another code editor? Not really
Do we want a native flutter code editor or a webview? For performance reasons we want native 100%
Do we trust unmaintained repos, or owners that are absent? Not at all
Do we want to render multimedia in code? Yes, for VS tutorials (diagrams, video, etc)
Do we want to reuse the code snippets in other parts of VS? Yes.
Do we want collaborative code editing? Yes.
Based on the questions listed above we can conclude we want to have Visual Editor in charge of rendering code blocks. We will disable rich text formatting on the code snippets and leave only code related features (highlights, markers, etc)
VE Blocks - Web, Cursor pointer on link hover #20
More info https://github.com/flutter/flutter/issues/81159 https://stackoverflow.com/questions/43583411/how-to-create-a-hyperlink-in-flutter-widget
VE Blocks - Unselecting the checkbox does not work
VE Blocks - Headings don't override the size of text #14
This feature was developed in Quill right before the fork. it was purely tested so a lot of quality issues snuck in. Including this one. We can't override the size of sized text with headings. this is standard behaviour in other editors. The last to change the text (font size or heading) has priority in controlling the line height. As you can see the line height changes but not the font size.
For example I checked Google Docs and they have the behaviour as described above. Although in some circumstances even their implementation is rather unreliable. For example if a heading has mixed sizes of text they all scale together until they cant. So if you have a line of text with small fonts and then super large fonts, their implementation wont override the font size. I'm not sure at all if this behaviour even makes sense. I'm eager to hear your thoughts.
https://user-images.githubusercontent.com/11160141/169512392-47e7b2d0-81bd-4bcb-92c4-263c40ac97f8.mov
VE Blocks - Subscript, Superscript #97