Merge pull request #4549 from roc-lang/editor_design_docs

improve/expand design docs for editor and plugins

design/editor/design.md

@@ -0,0 +1 @@
+Should the editor organize all UI into a tree for easy altering/communication with plugins?

design/editor/editor-ideas.md

@@ -238,7 +238,11 @@ e.g. you have a test `calculate_sum_test` that only uses the function `add`, whe
 - In the file explorer, auto-close subtree after unused for certain time.
 - Ability to right click error message > "create github issue".
 - Record (locally) all steps performed by editor + logs and make them searchable for user. The user should be able to scrub through these steps.
-
+- clustering of search results (rg like) based on statistics of result; amount of spaces, avg word length, amount of numbers...
+- Search engine to answer questions about your code base, logs, all intermediary values. Examples: search for "xy" in a string, search for xy in a variable name, show all intermediary values of index variable...
+- When a stacktrace is shown in the logs, highlight all lines of code in the editor that are in the stacktrace.
+- Double-click to select all child expressions of parent: [example](https://twitter.com/disconcision/status/1587156531203678208?s=20&t=GySrwPVnMB6rDKFqRuUcBw).
+- We should encourage users to ask editor something in the command window; e.g. "hide all types", "List docs", "switch light mode"... If the questions can not be matched to existing actions, the user should be given the option to share the question with editor developers so the action can be created or mapped to an existing action.
 
 #### Autocomplete
 
@@ -291,6 +295,7 @@ e.g. you have a test `calculate_sum_test` that only uses the function `add`, whe
   - Users with large private code bases could (re)train a publicly available error recovery model to experience benefits without having to share their code.
   - It could be useful to a user who is creating a function to show them the most similar function (type signature, name, comment) in a public+their private database. Say I was using a web framework and I just created a function that has a multipart form as argument, it would be great to have an example instantly available.
     - A simpler start for this idea without user data gathering: how the user a code snippet that is most similar to what they are currently writing. Snippets can be aggregated from examples, tests, docstrings at zero cost to the package/platform authors.
+    - Train ML model to rank snippets by likely usefulness to user.
     - See [codata](https://www.codota.com/code/java/classes/okhttp3.OkHttpClient) for inspiration on a snippet/example finder.
 - Fuzzy natural language based setting adjustment in search bar or with voice input: increase font size, enable autosave, switch to light theme...
 - Detect deviation of best practices, example case: alert developer when they are defining a color inline (rgb(30,30,30)) while all colors have been previously imported from a single file. See also [Codota](https://www.codota.com).
@@ -301,6 +306,7 @@ e.g. you have a test `calculate_sum_test` that only uses the function `add`, whe
 - Chatbot that can answer questions about the code base.
 - Smart navigation assistant to help you navigate with fuzzy text: take me to the false-interpreter's platform.
 - select some code (x='a'\ny='b') > Open transform command window > Type: concat chars > AI adds line: `concatenated = Char.concat 'a' 'b'`
+- Use terminal output to predict suggestions for files to navigate to.
 
 ## Testing
 
@@ -339,24 +345,6 @@ e.g. you have a test `calculate_sum_test` that only uses the function `add`, whe
 - Inclusion of step-by-step tutrials in Roc libraries, platforms or business specific code.
 - Having to set up your own website for a tutorial can be a lot of work, making it easy to make quality tutorials would make for a more delightful experience.
 
-## General Plugin Ideas
-
-### Ideas
-
-- Plugin to translate linux commands like curl to Roc code
-- Plugin to view diff between two texts
-- Plugin to present codebase to new developer or walk co-worker through a problem. Records sequence of filenames and line numbers.
-- A Logbook plugin. I've found that writing down steps and thoughts when you're implementing or debugging something can be really useful for later.
-If we make an integrated terminal, we can automatically add executed commands to this logbook. This plugin could have a publish button so you can produce useful "blogs" for others with minimal effort.
-
-### Inspiration
-
-- [Boop](https://github.com/IvanMathy/Boop) scriptable scratchpad for developers. Contains collection of useful conversions: json formatting, url encoding, encode to base64...
-- [processing](https://processing.org) Interactive editor, dragging left or right with mouse to change values. Instant results.
-- [flowistry](https://github.com/willcrichton/flowistry) easily track all named values in a certain expression throughout your program.
-- Match blocks of assembly with lines of code: [link](https://twitter.com/dgryski/status/1547952259828330498).
-- [livelits](https://hazel.org/build/livelits/) inline interactive plugin blocks
-
 ## High performance
 
 ### Inspiration
@@ -379,12 +367,6 @@ If we make an integrated terminal, we can automatically add executed commands to
 - [Duolingo](https://www.duolingo.com) app to learn languages
 - [Khan academy](https://www.khanacademy.org/) free quality education for everyone
 
-## Security
-
-- Remove permissions if plugin has not been used for a long time.
-- Log plugin actions that require a permission.
-- Show plugin that is currently using a permission, e.g. roc-core is reading from folder /gitrepos/hello in status bar and with a scrollable log.
-
 ## Accessibility
 
   - Visual Imapirments

design/editor/plugins/api.md

@@ -0,0 +1,3 @@
+- [Action state design document](https://docs.google.com/document/d/16qY4NGVOHu8mvInVD-ddTajZYSsFvFBvQON_hmyHGfo/edit?usp=drivesdk)
+- [Roc theme changer plugin concept study](https://gist.github.com/lukewilliamboswell/1b921641e7d68457ba88d81747c1bd44)
+- Plugin can register view (=UI) to editor; editor can use that view to render all occurrences of (a value of) that type.

design/editor/plugins/inspiration.md

@@ -0,0 +1,5 @@
+- [Hazel Livelits](https://hazel.org/papers/livelits-paper.pdf) interactive plugins, see GIF's [here](https://twitter.com/disconcision/status/1408155781120376833).
+- [Boop](https://github.com/IvanMathy/Boop) scriptable scratchpad for developers. Contains collection of useful conversions: json formatting, url encoding, encode to base64...
+- [processing](https://processing.org) Interactive editor, dragging left or right with mouse to change values. Instant results.
+- [flowistry](https://github.com/willcrichton/flowistry) easily track all named values in a certain expression throughout your program.
+- Match blocks of assembly with lines of code: [link](https://twitter.com/dgryski/status/1547952259828330498).

design/editor/plugins/plugin_use_cases.md

@@ -0,0 +1,19 @@
+# Bundled with package (=library)
+
+- Regex description to actual regex.
+- Color picker.
+- Visualising parser execution: [example](https://github.com/fasterthanlime/pegviz).
+
+# Standalone
+
+- Translating short pieces of code from another programming language to Roc. [Relevant research](https://www.youtube.com/watch?v=xTzFJIknh7E). Someone who only knows the R language could get started with Roc with less friction if they could quickly define a list R style (`lst <- c(1,2,3)`) and get it translated to Roc.
+- Translate linux commands like curl to Roc code.
+- Diff viewer
+- Plugin to present codebase to new developer or walk co-worker through a problem. Records sequence of filenames and line numbers.
+- Logbook; I've found that writing down steps and thoughts when you're implementing or debugging something can be really useful for later. If we make an integrated terminal, we can automatically add executed commands to this logbook. This plugin could have a publish button so you can produce useful "blogs" for others with minimal effort.
+- Upload selected code/file to gist.
+- Friendly/smart text filtering; be able to filter values by selecting a part. For example; logs contain `roc_expect_buffer_109680`, we select `109680`, numbers at identical positions are extracted.
+- Diagram rendering from text, similar to [mermaid](https://mermaid-js.github.io/mermaid/#/).
+- Pomodoro timer to remind you to take breaks regularly.
+
+

design/editor/plugins/security.md

@@ -0,0 +1,3 @@
+- Remove permissions if plugin has not been used for a long time.
+- Log plugin actions that require a permission.
+- Show plugin that is currently using a permission, e.g. roc-core is reading from folder /gitrepos/hello in status bar and with a scrollable log.

design/editor/plugins/ui_research.md

@@ -0,0 +1,33 @@
+# Inspiration
+
+## Plugin window organization
+
+- Notebooks:
+    + Jupyter Notebook
+        - ![notebook image](https://github.com/quantopian/pyfolio/blob/master/pyfolio/examples/sector_mappings_example.ipynb)
+        - The notebook’s scrollable nature makes embedding plugins in the UI easy and clean.
+    + Elixir Livebook
+        - [example video](https://youtu.be/lyiqw3O8d_A?t=246)
+    + Note: notebooks fit very well if you are trying to tell a story; for a tutorial, analyzing data, interactive textbook, prototyping… . I have not seen them used for large systems or codebases.
+
+- Glamorous toolkit:
+    + ![Gtoolkit overview](https://raw.githubusercontent.com/feenkcom/gtoolkit/main/doc/gtr-overview.png)
+    + multi-language notebook, code editor, software analysis platform, visualization engine, knowledge management system
+- Design software:
+    + blender
+        - ![blender screenshot](https://cdn.80.lv/api/upload/content/a0/60f703b067544.jpg)
+    + photoshop
+        - ![photoshop screenshot](https://www.startpage.com/av/proxy-image?piurl=https%3A%2F%2Fi.ytimg.com%2Fvi%2FiMo20Gqj-sM%2Fmaxresdefault.jpg&sp=1668869642T68632e7db288b83ef9c5bf202804c88f48718ba3fd052003e161e78c4e1adb79)
+    + gimp
+        - ![gimp screenshot](https://www.lifewire.com/thmb/R-Gy2C1RdRH_KbiaS04rPvehA7I=/1366x0/filters:no_upscale():max_bytes(150000):strip_icc():format(webp)/gimp-photo-open-6d392895064245ec8e3b1ecd09f0651a.jpg)
+- Music production software:
+    + Ableton Live
+        - ![ableton screenshot](https://i.pcmag.com/imagery/reviews/026WYE4XN99dDtWflTxyi5l-33.fit_lim.size_1152x.jpg)
+- Hazel livelit:
+    + Plugins are rendered inline.
+    + [link](https://hazel.org/build/livelits/), test with `let foo<tab>$color`
+
+
+# Prototyping
+
+- [Visually organizing plugin windows](https://docs.google.com/presentation/d/1Oc8w5lZw2dg2L5evt42d3FsmT2deYo4JNoqxNsh4q9M/edit?usp=drivesdk)