Add <tree> component for folder structure visualisations #1807

tlylt · 2022-03-07T16:33:19Z

What is the purpose of this pull request?

Overview of changes:
Fixes #1660

Provides a convenient way to create lightweight tree-like textual output, suitable for folder structure visualisations.
Syntax:

<tree>
Edit me to generate
  a
    nice
      tree
        diagram!
        :)
</tree>
<tree>
Edit me to generate
  - a
    - nice
    - tree
        - diagram!
        - :)
</tree>

To

Edit me to generate
└── a
    └── nice
        └── tree
            ├── diagram!
            └── :)

More details in UG's tree section

A summary of the work done:

feature development in core/src/plugins/default/markbind-plugin-tree.js
unit test in core/test/unit/plugins/default/tree.test.js
functional test in packages/cli/test/functional/test_site/testTree.md
UG inclusion under Using Component - Images & Diagrams - Tree
Migration of the existing folder structure code in UG over to use the new tree syntax, mainly in Reusing Contents
Update tests

Anything you'd like to highlight / discuss:

Initially thought of making a Vue component, but went with making a default plugin instead (since the feature itself is quite lightweight)
The currently supported syntax uses spaces + unordered list bullets for indication of indent/level, I am not sure whether I should also support (chop off) ordered list bullets (basically, numbers like 1., 2. etc).
The support for inline markdown/HTML elements works for most syntax, but not for tooltip/popover

<tooltip id="tt:trigger_id" content="This tooltip triggered by a trigger"></tooltip>

<tree>
C:/course/
  textbook/
    <tooltip content="hello">index.md</tooltip>
    <trigger for="tt:trigger_id">via trigger</trigger>
</tree>

Testing the above code will give:

<div class="tree">C:/course/
├── <span data-mb-component-type="tooltip" tabindex="0" content="hello" class="trigger"><!----> <!----> index.md</span>
└── <span tabindex="0" class="trigger"><!----> via trigger</span></div>

Notice the white space added in front of the words "index.md" and "via trigger". While the direct tooltip approach does not work on hover, the trigger approach works. Not too sure if this is a bug with the tooltip/trigger element or is it due to the newly added tree component.

Testing instructions:
Tests cases are added in

packages/cli/test/functional/test_site/testTree.md
packages/core/test/unit/plugins/default/tree.test.js

User guide section

tree
see some migration of the folder structure code in this page

Proposed commit message: (wrap lines at 72 characters)
Add component for folder structure visualisations

It is tedious to manually create tree-like structure diagrams.

Let's add a component to conveniently convert
an indented list of items into tree-like textual output.

This is especially useful for file system visualisations.

Checklist: ☑️

Updated the documentation for feature additions and enhancements
Added tests for bug fixes or features
Linked all related issues
No unrelated changes

jonahtanjz

Very nicely done @tlylt 👍 Tried it out and so far it is working well :)

Just a quick review on the design and documentation first.

packages/core/src/plugins/default/markbind-plugin-tree.css

docs/userGuide/syntax/tree.md

jonahtanjz · 2022-03-09T16:04:37Z

Notice the white space added in front of the words "index.md" and "via trigger". While the direct tooltip approach does not work on hover, the trigger approach works. Not too sure if this is a bug with the tooltip/trigger element or is it due to the newly added tree component.
<div class="tree">C:/course/
├── <span data-mb-component-type="tooltip" tabindex="0" content="hello" class="trigger">  > index.md</span>
└── <span tabindex="0" class="trigger"> via trigger</span></div>

Seems like an issue with the way the tree processes the node? Notice that the content="hello" attribute is still there on the HTML output which means the tooltip processor did not get to change the content into a <slot>.

If we try putting the tree code manually with the tooltip, it doesn't seem to have an issue.

<div class="tree">
  C:/course/
  └── textbook/
      └── <tooltip content="hello">index.md</tooltip>
</div>

Not entirely sure what is causing this but somehow after the tree plugin processes the code, the tooltip does not get processed.

tlylt · 2022-03-09T16:15:41Z

If we try putting the tree code manually with the tooltip, it doesn't seem to have an issue.
<div class="tree">
  C:/course/
  └── textbook/
      └── <tooltip content="hello">index.md</tooltip>
</div>
Not entirely sure what is causing this but somehow after the tree plugin processes the code, the tooltip does not get processed.

It seems like the problem of empty spaces added in front of the word 'index.md' is a separate issue. Is this a bug with the tooltip component? 🤔

jonahtanjz · 2022-03-09T16:28:46Z

It seems like the problem of empty spaces added in front of the word 'index.md' is a separate issue. Is this a bug with the tooltip component? 🤔

Seems like the the usual tooltip component will put in a white space before the text but this is usually ignored/removed with white-space: normal (default)

However, since the tree component has the css rule white-space: pre, white spaces will be preserved leading to the empty space.

I guess we can remove the white space generated from the tooltip/trigger components if possible.

tlylt · 2022-03-10T04:30:06Z

Seems like the the usual tooltip component will put in a white space before the text but this is usually ignored/removed with white-space: normal (default)

Seems like this is indeed the issue. Curious how did you find that out 😅? I was looking over the code for the Tooltip/Trigger Vue components and couldn't find something similar to that effect.

jonahtanjz · 2022-03-10T08:56:11Z

Seems like this is indeed the issue. Curious how did you find that out 😅? I was looking over the code for the Tooltip/Trigger Vue components and couldn't find something similar to that effect.

I noticed the white space by looking at the HTML code output on the browser. Since the Tooltip/Trigger component rely on the slot component for the content, which is transformed using the processAttributeWithoutOverride function, my guess is that the space is introduced during the processing of attributes here.

jonahtanjz

Other than the tooltip/trigger issue, I think this PR is good to merge.

Might also want to add a note in the documentation to show that tooltip/trigger is not supported in the tree component yet and open a new issue tracker for this.

EDIT: There seems to be some merge conflict as well.

jonahtanjz

Thanks @tlylt!

LGTM 👍

ang-zeyu · 2022-03-16T17:39:36Z

packages/core/src/plugins/default/markbind-plugin-tree.js

+    }
+    node.name = 'div';
+    node.attribs.class = node.attribs.class ? `${node.attribs.class} tree` : 'tree';
+    node.children[0].data = TreeNode.visualize(node.children[0].data);


DomParser nodes returned by htmlparser have various types, with the isSpecial option specified the (only) child is treated as text (much like script/style tags).

You could use cheerio apis here instead to attach the visualized string as html, which solves the main (non-whitespace) issue with #1831.

Debugger (do set it up if you haven't! might be rather useful for resolving low-level issueslike this 🙂):

You could use cheerio apis here instead to attach the visualized string as html

Do you mean changing it to something like:

processNode: (pluginContext, node) => { if (node.name !== 'tree') { return; } cheerio(node).text(TreeNode.visualize(cheerio(node).text())); cheerio(node).addClass('tree'); node.name = 'div'; },

I tried this but doesn't seem to resolve the issue with tooltips (still has white space + does not show up on hover).

yup, but this is the wrong method .text( (still attaching as text, not html)

reping in case this was missed @tlylt.
though not urgent, we can put up an issue if no time to test it yet.

reping in case this was missed @tlylt. though not urgent, we can put up an issue if no time to test it yet.

Thanks for the reminder. I have tested and setting it via .html (iirc) does achieve the effect as you mentioned. This resolves the white-space issue but triggers are still quite buggy/ not functional. I have #1831 to keep track of this and was thinking to investigate along with the comment #1831 (comment) before pushing a fix.

damithc · 2022-03-24T08:24:37Z

Minor: perhaps we can also add something like this to the examples given in the documentation? (it uses :far-folder: and far-file). I prefer to give examples that shows how the feature is used in realistic 'best-effect' scenarios.

tlylt added 13 commits March 6, 2022 10:05

initial tree plugin setup

8287729

refactor

4b7b773

add unit test

48d1c19

refactor

14f1921

migrate docs

ed46108

fix regex

a2e5a37

add docs

4166188

add v-pre

2a7c38b

update test

cfd74c3

update css

dd5db3b

update test artifact

91c33a4

undo v-pre for inline html

04f3765

updatetest

f8bf784

jonahtanjz reviewed Mar 9, 2022

View reviewed changes

packages/core/src/plugins/default/markbind-plugin-tree.css Show resolved Hide resolved

docs/userGuide/syntax/tree.md Outdated Show resolved Hide resolved

jonahtanjz requested a review from ryoarmanda March 9, 2022 15:20

tlylt added 2 commits March 9, 2022 23:57

Update based on review

039096f

update test

e0f031e

ang-zeyu mentioned this pull request Mar 10, 2022

Maintain markdown-it-footnotes state across all of a single page's contents #1814

Open

jonahtanjz reviewed Mar 15, 2022

View reviewed changes

tlylt added 5 commits March 15, 2022 20:18

Merge branch 'master' into tree

45ee8b4

update test

d10ad05

add warning

a3ba617

Merge branch 'master' into tree

28c4c18

update tests

ea298ce

tlylt mentioned this pull request Mar 15, 2022

Pop-Ups like tooltip/trigger do not work within the tree component #1831

Open

jonahtanjz approved these changes Mar 15, 2022

View reviewed changes

jonahtanjz added this to the 4.0 milestone Mar 15, 2022

jonahtanjz merged commit 3d8495a into MarkBind:master Mar 16, 2022

ang-zeyu reviewed Mar 16, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add <tree> component for folder structure visualisations #1807

Add <tree> component for folder structure visualisations #1807

tlylt commented Mar 7, 2022 •

edited

Loading

jonahtanjz left a comment

jonahtanjz commented Mar 9, 2022

tlylt commented Mar 9, 2022

jonahtanjz commented Mar 9, 2022 •

edited

Loading

tlylt commented Mar 10, 2022

jonahtanjz commented Mar 10, 2022

jonahtanjz left a comment •

edited

Loading

jonahtanjz left a comment

ang-zeyu Mar 16, 2022

ang-zeyu Mar 16, 2022 •

edited

Loading

tlylt Mar 24, 2022

ang-zeyu Mar 25, 2022

ang-zeyu Apr 19, 2022

tlylt Apr 19, 2022

damithc commented Mar 24, 2022

Add <tree> component for folder structure visualisations #1807

Add <tree> component for folder structure visualisations #1807

Conversation

tlylt commented Mar 7, 2022 • edited Loading

jonahtanjz left a comment

Choose a reason for hiding this comment

jonahtanjz commented Mar 9, 2022

tlylt commented Mar 9, 2022

jonahtanjz commented Mar 9, 2022 • edited Loading

tlylt commented Mar 10, 2022

jonahtanjz commented Mar 10, 2022

jonahtanjz left a comment • edited Loading

Choose a reason for hiding this comment

jonahtanjz left a comment

Choose a reason for hiding this comment

ang-zeyu Mar 16, 2022

Choose a reason for hiding this comment

ang-zeyu Mar 16, 2022 • edited Loading

Choose a reason for hiding this comment

tlylt Mar 24, 2022

Choose a reason for hiding this comment

ang-zeyu Mar 25, 2022

Choose a reason for hiding this comment

ang-zeyu Apr 19, 2022

Choose a reason for hiding this comment

tlylt Apr 19, 2022

Choose a reason for hiding this comment

damithc commented Mar 24, 2022

tlylt commented Mar 7, 2022 •

edited

Loading

jonahtanjz commented Mar 9, 2022 •

edited

Loading

jonahtanjz left a comment •

edited

Loading

ang-zeyu Mar 16, 2022 •

edited

Loading