Discussion/UI/UX: Handling of sharp for use with markdown and links

[christianlupus]

During my code review of #900, I found a UI/UX issue that needs to be specified before an implementation can be achieved. I am asking @seyfeb and @MarcelRobitaille for their opinions. Anyone else is also invited to share their options/thoughts as well.

Context

We are using markdown for formating the description and the tools, ingredients, and instruction lists. In MD the # is a special symbol with different meanings. For one, there is the heading of every level starting with an appropriate number of #s. Additionally, there is the non-standard extension of MD that and word matching the regex #r/[0-9]+ is replaced by a link to the corresponding recipe.

Current behavior

We have a listener in place that will trigger a popup menu as soon as a # is typed/detected. The user is presented with a searchable list of all recipes. When the user clicks on a recipe, the link to said recipe is inserted in the corresponding location.

Use-cases

Let's have a look at what a user might want to achieve. We have these cases

1. User types # and selects a recipe. The result #r/1234 should be inserted.
2. User wants to type a headline. That is at the beginning of a line a # is typed.
3. User wants a literal # within the text.
4. User mistyped the # and wants to abort completely. No input should be inserted.

I am not seeing any further cases but I might as well have missed a case.

Currently, for number 2+3 the user aborts the dialog and gets the left-over #.

Suggestions on desired UI behavior

Here are a few ideas on how the app could behave. Feel free to modify or add new suggestions.

Variant A: Current behavior

As soon as a # is typed, the dialog is shown. When selecting a recipe, the text is inserted. When aborting, the literal # is kept. The user is responsible for manually removing the # if it is not intended.

Variant B: Using modifier key

One could add the option to add a modifier key when the user wants a literal #. As some keyboard layouts need the shift modifier to type the #, one option was to type Ctrl+# for a literal #.

Variant C: Additional option in popup menu

One could add an option to the list of recipes to allow the user to insert the literal #. This could be combined with a press on #. So, the short solution was to press ## for a single literal #. If the user aborted the popup menu, nothing was to be inserted.

Optional: Allowing headlines

We could check if the line starts with the #s. If yes, we could assume that the user wants to type a heading and just pass the # literally. This will prevent the popup to appear if the user wants to start a line with a link (like #r/123 is an example recipe to use this dough.).

On the other side is the question if we want to encourage the usage of headlines as this might break the general structure of the recipe view.

[seyfeb]

First, I’m a bit biased, since I built the current behavior. I understand that it can feel cumbersome that the popup appears if you simply want to type a # symbol and no link.

Variant B (modifier key) seems a bit constructed and like a very hidden feature, if we don’t actively promote it.

Variant C might work if explained correctly in the menu.

I would like to add Variant D: Hide the popup when Space is pressed immediately after the # and keep the #

[MarcelRobitaille]

Thank you for starting this discussion.

I agree with @seyfeb that option b would probably not be known if not promoted.

Option c could work, but I don't think it would be what I expect as a user.

I assume that this feature and the choice of # was used to mimick Github. Maybe the solution (Variant E) could be to make the popup less obtrusive. The popup would not cover up the cursor and the user can keep typing to close the popup and keep the #.

[christianlupus]

I was just collecting ideas right now. The discussion is open and any constructive opinion should be heard.

I was thinking by variant B of the newline issue.

For variant C I would suggest adding an additional entry or a text to the popup that indicates how to add the literal #. The same works for variant D.

Do we have a good way to implement variant E in terms of @nextcloud/vue, @seyfeb? (I labeled the suggestion by @MarcelRobitaille with E for reference.)

[MarcelRobitaille]

I started to use ## to create groups for my ingredients as recommended in #311. Currently, I am unable to type a #. I only get the popup.

the user aborts the dialog and gets the left-over #

This is not working for me in 0.9.10 or on master. When I press esc (I assume that's what abort means, I don't see an exit button), I nothing is inserted into the text field.

I really think that the popup should be as unobtrusive as possible, especially if ## is the recommended way to group ingredients. I would like to see variant E, B, or D (in order of preference). I think GitHub does it very well. You type # and get an unobtrusive list of options. But importantly, if you type a second # or a space, the list disappears. You can type the ID of the issue/PR, or you can type some keywords from the name. Pressing enter selects the top option.

Peek.2022-03-21.00-24.mp4

As for how to implement E in terms of @nextcloud/vue, I am not sure if it can be done with this library, but I don't think it would be that hard to make it ourselves. I see it as a simple ul with some buttons inside. As you type, we filter down the list of options shown in the ul. Clicking a button inserts its ID into the text. Position the ul relative to the cursor position (possible, but seems difficult).

[seyfeb]

I agree that we could simply try to mimic the github-issue-reference behavior:

First # inserts the character in the textfield and shows references popup. Then for the next possibilities we have

• # again: closes popup and inserts second #
• Space: closes popup, inserts space, keeps first #
• esc: (here I would suggest to implement a different behavior: closes popup, keeps #, active cursor behind first # (that’s the difference. github blurs focus on the input field)
• backspace: closes popup, deletes first #
• up/down arrow navigates through reference list
• left/right arrow closes popup, navigates through text input
• enter: insert reference to currently select recipe in the text (this requires one recipe to be selected)
• other keys: Continue inserting characters after the #, used for searching the list; if no match is found, hide the popup

The complete behavior doesn’t need to be implemented in one go, though.

As for the positioning of the references. I’m all in for making this visually neater, but beware this might require some effort to make it behave nicely on every platform (mobile/desktop), not overlapping with screen borders, well visible and navigable, etc ;)

[MarcelRobitaille]

Thanks for your detailed comments @seyfeb. I agree with all of those points.

this might require some effort to make it behave nicely on every platform (mobile/desktop), not overlapping with screen borders, well visible and navigable, etc ;)

I am up for the challenge!

[christianlupus]

That was a very precise description @seyfeb! Thanks!

[MarcelRobitaille]

Do we have enough information to make a decision on a variant?

[christianlupus]

Yes, think this should be well specified enough.

How do we proceed from here? Volunteers for implementing this?

[MarcelRobitaille]

I am interested in this, but I am very busy these days. I cannot guarantee it will be done soon.

[seyfeb]

Related #907

[MarcelRobitaille]

Have we decided on this implementation? I know everybody put thumbs up to that, but I don't think we officially chose a variant.

[christianlupus]

I would say so. At least I put my vote on it.

[seyfeb]

Me too. For the implementation we should keep #991 in mind, which might or might not be solved at the same

[MarcelRobitaille]

Ok, I agree that that is the best implementation. However, in that case, I think we should not do #907. If the user wanted to type a #, then I don't think we should blur the background and the textfield they're writing in. The popup should be obvious enough that the user knows what's going on, but not hide the UI element they are trying to interact with. That is my opinion and I am open to hearing another perspective.

I will keep #991 in mind.

[christianlupus]

Regarding #907: This should still be active for all modal dialogs, I think. The new editor should of course not get blurred or similar when writing (see GitHub). But for now, that should be done. I'd say we delay the issue #907 until the output of the new UI is fixed. Adding some fancy styling like blurring is definitively possible later.

[christianlupus]

I fear I broke the current behavior with my fix in #1050. No overlay is shown at the moment at all.

Do you see any chance to have a look at this in the closer future, @MarcelRobitaille?

[MarcelRobitaille]

Hi @christianlupus. I don't think I will have a chance to look at this for at least a few weeks. I am at a critical point in my master's degree right now. I will have plenty of free time after I graduate though. If this is urgent, I don't mind if someone takes over this task.

[christianlupus]

I would not consider it urgent. If there is anyone considering it urgent, he/she might want to implement it themselves 😈. I just did not see any progress and no obvious hindering reason. Some personal issues are counting for sure. A few weeks are perfectly fine.

[MarcelRobitaille]

Here's a progress update. The video shows all of the functionality outlined by @seyfeb.

There is one additional case not mentioned in that comment: the popup should be hidden on blur of the textarea.

Peek.2022-07-21.15-32.mp4

Remaining tasks:

• Generalization: It currently only works on EditInputGroup. EditInputField is not updated and the markdown editor is currently broken even with the old implementation as @christianlupus mentioned. I am thinking of how best to generalise this. I am wondering if we should implement this only once in EditInputField and re-use that component in EditInputGroup. I am noticing some duplicated logic between them, which will only get worse if I add all of these changes to EditInputField as well.
• Responsiveness: Right now, it is left-aligned to the #. It will thus overflow the screen if the # appears near the right side of the input. It is also possible that it would be too wide and/or off screen (below the virtual keyboard) for mobile devices.
• Fuzzy searching: Currently, the full "search text" (text between # and caret) has to be a substring of the recipe id: title for the recipe to show up in the dropdown.
• Styling: The styling could probably be better. I'm not a designer. I am using the standard CSS variables though, so at least it's readable in dark mode.
  

FYI here is the branch where I am working on this: https://github.com/MarcelRobitaille/cookbook/commits/903-link-suggestions

[christianlupus]

I must say that I am impressed with the result in the video.

One idea, I have with mobile devices: Can the overlay be made width:100%; left:0 to make it appear as a block and prevent overflowing to the right?

Out of curiosity: Can you scroll the list if it gets longer?

In general, I would favor smaller and easier pieces over fewer and more powerful ones. So, if you can manage to remove the duplication by changing the architecture in/at the EditInputField object, I would go for it. (Maybe a Vue mixin might be useful to prevent code duplication?)

I'd say that the searching with non-fuzzy should be bo problem. At worst, one could issue a delayed API call to make a more complex search. But I'd say not now. KISS.

As far as I have seen, the styling can be altered if it was required. If we have something that seems built from one block, we can consider doing an app review #943. If you have dedicated questions, you can still ask there in the group for individual design guidance.

[seyfeb]

From the video this looks very nice! I have never used mixins, but from the documentation it might be a possible to have the shared code for triggering the pop-up and handling the selected recipe in a shared mixin.

Since this also requires shared html, I would suggest to put the pop-up and the navigation/selection/cancellation logic into a separate vue component which is included by any component requiring it. The component could emit events when the user takes an action which is then handled by the parent (e. g. the selection of a recipe).

[MarcelRobitaille]

I must say that I am impressed with the result in the video.

Thank you 😄

One idea, I have with mobile devices: Can the overlay be made width:100%; left:0 to make it appear as a block and prevent overflowing to the right?

Yes, I thought of something like that for small screen sizes. I'll work on it.

Out of curiosity: Can you scroll the list if it gets longer?

Currently no, the element will be as long as it needs to be to fit all of its children. I will add a maximum height and scrolling.

In general, I would favor smaller and easier pieces over fewer and more powerful ones. So, if you can manage to remove the duplication by changing the architecture in/at the EditInputField object, I would go for it. (Maybe a Vue mixin might be useful to prevent code duplication?)

I agree. I am not familiar with Vue mixin, I will look into it.

I'd say that the searching with non-fuzzy should be bo problem. At worst, one could issue a delayed API call to make a more complex search. But I'd say not now. KISS.

I agree as well. KISS, at least for the initial implementation.