feat: register a custom editor component named Toggle Section

[bodom0015]

Problem

DecapCMS allows us to create custom editor components to render complex Markdown

Fixes #342

Approach

• feat: create a custom editor component that will produce standard <details>/<summary> toggles as HTML
  • Prevent nesting one Toggle Section within another Toggle Section

Example:

Which produces the following HTML:

<details name="example"><summary>1. Access varies depending on where you are (origin)</summary><p>Imagine living in downtown Chicago, where it is easy to catch a bus or hop on the subway to get to work, visit friends, or run errands. If the transit system is well-connected, and stops are just a short walk from your home, this could make it convenient for you to rely on public transportation. Now, if someone lives in a small rural town where public transit might be limited to a few bus routes that only run a couple of times a day. The nearest bus stop could be several miles away, making it inconvenient to rely on public transportation. At the same time, some individuals may find it convenient to obtain services near their work or shopping locations, indicating that daily activity spaces other than residential locations can be more representative of origin in measuring public transit calculations. This highlights the importance of origin (location) in accessibility decision making.</p></details>

TODOs

• Newline characters within content are not well-supported. This will be problematic for less technical users (supporting which is the whole point of using a CMS system to begin with) regex has been adjusted to allow newline characters within collapsible content :+1:
• Images embedded in content do not play well with the editor - this may be because of the newline support mentioned above with the corrected newline behavior (see above), this problem appears to have gone away and we can now embed images within collapsible content :+1:

How to Test

1. Navigate to https://deploy-preview-350--cheerful-treacle-913a24.netlify.app/admin/index.html
2. Click on Guides on the left, and choose the "Public Transit Equity" guide from the list
   • You should see an Editor on the left, and a preview of the contents on the right
3. Ensure that the editor is set to "Rich-text" mode
4. Expand the "+" dropdown on the editor
   • You should see "Toggle Section" listed here - this is our newly-added component
5. Choose "Toggle Section" from the list
   • You should see a new widget named "Toggle Section" appear in the editor below
   • You should see that this widget has 3 separate inputs: title, content, group
6. Enter a value for Title - this will be the clickable header when the section is collapsed
7. Enter a value for Content - this will be Markdown that becomes the main content for when the section is expanded
   • Expand the "+" button here - you should see that Toggle Section is not listed as an option within a Toggle Section
8. (optional) Enter a value for Group - if specified, only a single section from the same group can be expanded at once
9. Change between the "Rich-text" and "Markdown" modes in the editor
   • You should see the widget is converted to its raw HTML format (see above) and then back again
10. Try to come up with weird edge cases that might break this widget
    • NOTE: The HTML form must be a produced as a single line, or else we have trouble detecting the end of one Toggle Section and the start of another

[netlify[bot]]

✅ Deploy Preview for cheerful-treacle-913a24 ready!

Name	Link
🔨 Latest commit	e9e9faa111f9040430a0b552e6acd4a9ba6c4e29
🔍 Latest deploy log	https://app.netlify.com/sites/cheerful-treacle-913a24/deploys/671ffe21ae87600008bbb224
😎 Deploy Preview	https://deploy-preview-350--cheerful-treacle-913a24.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[mradamcox]

Looking good so far! However, it seems like even though the Markdown widget is used for the content, it doesn't get rendered properly:

Better behavior would either

1. (preferred) render markdown to HTML in the preview as well as in the final page (I didn't check the final page, but assume it isn't working there either), or
2. (alternative) replace the markdown widget for the content field with a plain text widget.

I'm assuming we can write raw HTML into this content regardless of what widget is used, so if that is the only way we can have complex content, like lists or images, then we should force the user to do that, and not provide a markdown widget that doesn't work.

[bodom0015]

Thank you for the feedback, @mradamcox!

Sorry, I had based this implementation off of the DecapCMS example "Collapsible Note": https://decapcms.org/docs/custom-widgets/#registereditorcomponent

They specified the widget type as markdown, so I assumed this would handle Markdown appropriately by default 🤔 Apparently this case needed some special care and we now use marked to parse the Markdown within the Toggle Section: https://github.com/markedjs/marked

Gotchas involved that we're working around here:

• there must be a space before markdown content or else it will not render properly - I think I've added this in the background so the user shouldn't need to worry about it
• single-quoted attributes appeared to work best with the RemoteMDX version on /guides/[slug], even though both single and double quotes are accepted by the editor in DecapCMS
• regex needed some special care to properly detect the end of the value of the name attribute - without this there were some errors parsing group name out of adjacent Toggle Sections
• This does NOT support nested Toggle Sections, even though the widget is offered in the sub-editor as well - after converting to Markdown and back again, the sub-sub-editors will be lost since is it is not trivial to parse out these nested values using regex

Things that I should be well tested:

• Adding a Toggle Section via the button in the Editor
• Converting entire document back and forth in Rich-text vs Markdown this transformation works both ways
• Inserting Markdown values into the content of the Toggle Section
• Creating / Converting Toggle Sections both with and without group specified
• All of the above verified on the resulting /guides/ view as well (rendered via RemoteMDX)

[bodom0015]

@mradamcox yes, it looks like we were able to prevent the user from adding one Toggle Section within an existing Toggle Section :+1:

          {
            name: 'content',
            label: 'Content',
            widget: 'markdown',
            // exclude toggle-section from being nested inside of another toggle-section
            editor_components: [ "image", "code-block" ],
            required: true
          },

Adding the editor_components property allows us to customize which buttons are offered under the + button in the sub-editor :tada:

Similarly, specifying buttons lets us choose which buttons are shown on the editor (aside from +) For example: choosing buttons: [ "bold" ] will hide italics, underline, etc and only show the bold button :+1:

[mradamcox]

Ok, perfect, thanks for figuring that out. It will make it a lot easier to add custom editor components and only use them in certain instances of the markdown widget. One final request for this PR: Could you add cursor: pointer style to the summary element, so that the toggle looks a little bit more like a button when you hover over it? After that, ready to merge!

[bodom0015]

@mradamcox awesome! I was able to add this style pretty easily into our rendered version of the CMS (e.g. /guides/public-transit-equity)

I didn't see an easy way to adjust this in the DecapCMS preview as well, but I can spend some time to look into that if it is important?