search

theRAPTLab / gsgo

GEM-STEP Foundation repo migrated from GitLab June 2023
1 stars 1 forks source link

Feature: Bookmarks and custom styles #763

Closed benloh closed 10 months ago

benloh commented 10 months ago

Overview

This adds a number of comment-related features to the system.

Comment Styles

Added a new preferences system to define comment styles. There are three pieces to this:

1. Preferences Loader

2. Defining Comment Styles

_comment_types.toml help text

# PREFERENCES
#
#   Preferences are site-wide settings that apply to all projets.
#
#   Current Preferences support:
#     * Comment Types
#
# Comment Types
#   Comment Types are used to define the visual display of comments
#   in the ScriptEditor views.  You can define:
#     * `matchString` -- the search string used to set the visual style
#     * `cssClass` -- use a pre-defined css class (from `gem-ui.css`)
#     * `color` / `backgroundColor` -- css colors to use inplace of cssClasses
#     * `help` -- Short help blurb to display in the comment edit pane
#     * `isBookmark` -- flag to mark the comment type as a bookmark, 
#                       selectable from the ScriptEditor script lines view
#
#   To set the comment colors, use either:
#     A.`cssClass` to one of the predefined styles, or...
#        - commentKeyHeader
#        - explanationCommentHeader
#        - explanationCommentBody
#        - changeCommentHeader
#        - changeCommentBody
#     B. 'color' and/or 'backgroundColor' to override the color
#        You can use either 'color', or 'backgroundColor' or both.
#        Any colors defined will override the cssClass style.
#        Colors are defined as css values.  You can use:
#        * hexadecimal "#rgb" "#rrggbb", e.g. "#f00" for red
#        * rgb alpha "rgba(r,g,b,a)", e.g. "rgba(255,0,0,0.5)" for a transparent red
# 
#   You can override existing styles by adding them by using the
#   same `matchString` in the COMMENTTYPEMAP defined in
#   `gs_packages/gem-srv/src/modules/sim/script/tools/comment-utilities.ts`

3. Inputting Comment Text and Using Comment Styles

Comment lines can now be selected and edited via the wizard. In addition, you can now select a comment style via a popup selection menu and the full comment line will be automatically generated.

Technical Background: GEMSCRIPT scripts are text lines that are parsed and converted into tokens corresponding to keywords and parameters for each line of script. The input UI system uses an elaborate system of components to convert the keywords and parameters into the wizard UI. Comments however are not strictly speaking keywords. In order to provide a wizard UI for comments, we construct a secondary UI that handles the destructuring of comment text into prefix styles and comment body text so that they can be independently edited, and the reconstructed into a single comment line. See cf91c683ee19c30fc640a8b8a904135ab1de5069.

screenshot_1306

Bookmarks

Bookmarks can be added to GEMSCRIPT code. When opening a script, users can select a bookmark from a list of bookmarks and automatically scroll to the selected line and enable editing for the line.

screenshot_1300

Addresses #751, #758

To Do

benloh commented 10 months ago

@jdanish This is a WIP peek at bookmarks to make sure they do what you want. Currently any comment that is labeled as ✏️ LETS or ✏️ CHANGE will be added as bookmarks.

To Test

  1. Open a script editor
  2. Look for "Bookmarks" near the top of the screen.
  3. Select a bookmark to jump to the selected line.

screenshot_1300

The specific implementation of the style definitions is tbd, pending resolution of #758.

Please check out the dev-bl/comment branch (note the character updates have not been merged, so use wetlands_beavers_building to avoid errors).

jdanish commented 10 months ago

Cool. I assume it'll be easy to change the target token later? Also, I notice the bookmarks don't move the code view. I think we can live with that assuming it's a hassle to change. I like the direction overall, thanks!

benloh commented 10 months ago

Hmm...selecting a bookmarks should scroll the code view. Is that not working? We're still working on the match string for selecting the comment style and the wizard comment editing.

jdanish commented 10 months ago

In wetlands_beaver_building it doesn't seem to be working and I see this error in console for the script popup in case that matters?

Screenshot 2023-08-22 at 12 03 11 PM
benloh commented 10 months ago

Oh...two things: 1) The defaultValue warning is already fixed with the agent2character branch. It needs to be merged. 2) The scrolling works for the Wizard view but not the Code view. We don't have a mechanism in Code view for scrolling or selecting a line. I'll remove it from the view. Technically the Line view (right panel) should also not be shown in code view. So I should remove that. (Unless having bookmarks in the code view is very important? We'd have to build a new system to handle that and to show the selected line).

benloh commented 10 months ago

@jdanish In phase 2 of this work, we have rudimentary support for editing and selecting styles. Please give the dev-bl/comments branch a whirl to see if it does what you expect.

Updated main PR description with these changes.

Inputting Comment Text and Using Comment Styles

Comment lines can now be selected and edited via the wizard. In addition, you can now select a comment style via a popup selection menu and the full comment line will be automatically generated.

Technical Background: GEMSCRIPT scripts are text lines that are parsed and converted into tokens corresponding to keywords and parameters for each line of script. The input UI system uses an elaborate system of components to convert the keywords and parameters into the wizard UI. Comments however are not strictly speaking keywords. In order to provide a wizard UI for comments, we construct a secondary UI that handles the destructuring of comment text into prefix styles and comment body text so that they can be independently edited, and the reconstructed into a single comment line. See cf91c683ee19c30fc640a8b8a904135ab1de5069.

screenshot_1306

jdanish commented 10 months ago

Cool! Would it be hard to include in the comment style definition some basic use info / help text or at the least have a check box or flag to indicate which ones are bookmarks?

The display of _comment is a bit odd, but not the end of the world. If it could read was comment or // or similar that'd be cool.

Not unique to comments, but I just realized if you pick a comment and click cancel it leaves the window on the right in an odd state. But it's not a crash, so I would consider leaving it until the other things are done. I can write it up as an issue to file under "if we have time" unless you think it is more foundational?

benloh commented 10 months ago

comment help / bookmark

Hmm...this gets really messy with all of that info. If we're stuffing the key text along with a bookmark icon and explanation text, the line can get really long. Unfortunately without creating a new new type of component, we can't easily style the menu.

screenshot_1310 (Pretend that "--explanationCommentHeader--" displays "🔎 WHAT")

The other approach would be to show the help text AFTER you selected the item, but's unwieldy too.

Another method would be to show a whole formatted lookup table, but will eat up a lot of vertical space.

Will have to think about this some more...

The display of _comment is a bit odd, but not the end of the world. If it could read was comment or // or similar that'd be cool.

The problem is that when you pick a keyword with a new line, you would have to choose "//" as the keyword. I thought "_comment" would be a little clearer in spite of the disconnect between "//" and "_comment"?

screenshot_1307

jdanish commented 10 months ago

Hm. Is it possible to remove the underscore from comment? Otherwise yeah let’s leave it all for now…

benloh commented 10 months ago

Not unique to comments, but I just realized if you pick a comment and click cancel it leaves the window on the right in an odd state.

483a0b978b8353ef1cb6fe6fd58d87cff21911c1 fixes the weird "Cancel" state.

benloh commented 10 months ago

@jdanish This was pretty hairy, but I think I have this working now. It's on it's own branch for now for code clarity.

Please check out dev-bl/comment2slashes branch.

The fixes:

What do you think?

jdanish commented 10 months ago

Wouldn't it be "keyword" instead of "//" above? If that's a hassle, leave it as-is.

Otherwise, how about this, which I think is not perfect but slightly more readable and works for now?

Screenshot 2023-08-30 at 7 12 24 PM

Changed lines in SlotEditor around 139 to be:

<option key={optionkey} value={key}> {key}: {val.help} {val.isBookmark ? '🔖' : ''} </option>

Otherwise I think this is good enough and we can always leave off the help by not entering any? And then we can adapt once we see it in front of kids / next grant.

benloh commented 10 months ago

@jdanish most of comment style should now be working. Please check out the dev-bl/comment-styles branch.

We've added new npm library (@iarna/toml to support .TOML files), so please run npm ci.

Phase 3

Added a new preferences system to define comment styles. There are two pieces to this:

1. Preferences Loader

2. Comment Types Preferences File

_comment_types.toml help text

# PREFERENCES
#
#   Preferences are site-wide settings that apply to all projets.
#
#   Current Preferences support:
#     * Comment Types
#
# Comment Types
#   Comment Types are used to define the visual display of comments
#   in the ScriptEditor views.  You can define:
#     * `matchString` -- the search string used to set the visual style
#     * `cssClass` -- use a pre-defined css class (from `gem-ui.css`)
#     * `color` / `backgroundColor` -- css colors to use inplace of cssClasses
#     * `help` -- Short help blurb to display in the comment edit pane
#     * `isBookmark` -- flag to mark the comment type as a bookmark, 
#                       selectable from the ScriptEditor script lines view
#
#   To set the comment colors, use either:
#     A.`cssClass` to one of the predefined styles, or...
#        - commentKeyHeader
#        - explanationCommentHeader
#        - explanationCommentBody
#        - changeCommentHeader
#        - changeCommentBody
#     B. 'color' and/or 'backgroundColor' to override the color
#        You can use either 'color', or 'backgroundColor' or both.
#        Any colors defined will override the cssClass style.
#        Colors are defined as css values.  You can use:
#        * hexadecimal "#rgb" "#rrggbb", e.g. "#f00" for red
#        * rgb alpha "rgba(r,g,b,a)", e.g. "rgba(255,0,0,0.5)" for a transparent red
# 
#   You can override existing styles by adding them by using the
#   same `matchString` in the COMMENTTYPEMAP defined in
#   `gs_packages/gem-srv/src/modules/sim/script/tools/comment-utilities.ts`
jdanish commented 10 months ago

Sorry, but how do I run it? I tried dropping the sample file into art-assets (top level, renamed to just toml) but I get this error after running npm ci:

`internal/modules/cjs/loader.js:905 throw err; ^

Error: Cannot find module 'ws' Require stack:

benloh commented 10 months ago

Sorry for the confusion.

You should: a. checkout dev-bl/comment-styles b. run nvm use c. run npm ci d. run npm run build -- we changed some server side so things need to be rebuilt e rename the file from _comment_types.toml.txt to _comment_types.toml f. drop the file into /gsgo/gs_assets/art-asset/preferences/_comment_types.toml g. run npm run dev

jdanish commented 10 months ago

Thanks, seems to be working now. Seeing this warning in the console in case it matters:

Screenshot 2023-09-02 at 8 04 29 AM
benloh commented 10 months ago

Thanks, seems to be working now. Seeing this warning in the console in case it matters: Screenshot 2023-09-02 at 8 04 29 AM

Great! The warning was there to let you know that the test _comment_types.toml file was overriding the default WHAT type and re-defining it to something new. I figured it'd be helpful to let you know when something is being redefined. I can remove it if you'd rather not have that warning.

One thing you might do is revisit the definitions in comment-utilties.ts to make sure these are the styles you want defined "burned" into the code (they are the same ones you and Morgan had originally defined). If figure it's better to have a few built-in.

jdanish commented 10 months ago

Awesome. I took the liberty of committing a version of comment-styles that streamlines the set of comment types, and also re-words the warning label. I can undo if needed. This is otherwise looking good to me!

benloh commented 10 months ago

Fixed the scrolling bug. 34855b8b59c4f3a923846473319d2c8fd200b348

benloh commented 10 months ago

To keep the feature PR more consistent, we're going to merge dev-bl/comment2slashes and dev-bl/coment-styles into `dev-bl/comment'.

(The original PR was based on dev-bl/comment.

benloh commented 10 months ago

@jdanish I think this is finally ready for review.

benloh commented 10 months ago

Updated wiki: https://github.com/theRAPTLab/gsgo/wiki/Comments