Information about rewrite endeavor?

[hannahhoward]

Question

Hello! From following your issues/PRs, I can tell you've got a major rewrite underway (task/rewrite). It's exciting Formidable/Spectacle is devoting the resources to do this. I would love to hear, for those in the audience:

1. What are your major goals for this rewrite?
2. What problems with the existing codebase do you aim to address?
3. Do you want help from the community? If so, how can the community best help?

Background Info/Attempts

I'm a frequent spectacle user (THANK YOU SO MUCH!). So much so that I maintain a fork of spectacle-boilerplate with a ton of customizations... which has led me down a few rabbit holes in the code base to see why yall might undertake this endeavor. But I'm curious what you all are up to with this-- and I did try to do my due diligence in finding out what's up but don't see much information other than lots of pull requests.

[kale-stew]

Hi @hannahhoward! We have indeed been taking on a rewrite of the library, good eye. I can address your questions at a high-level, but as this effort is still underway and we anticipate another three weeks of work before it's stable enough for a release, there will likely be more details to announce in the near future. 🙂

1. Our major goals are to

   • make Spectacle more approachable for beginners (both using and contributing)
   • prioritizing an MDX flow
   • allow for easily templated styles and layouts
   • eliminate the need for separately maintained boilerplate and scripts

2. There are a few problems I would like to address, but the central issue is how bloated our Manager component is. It's 939 lines, containing majority of the rendering logic. This has led to us introducing a handful of regressions after releasing a huge feature - currently, a number of existing documented features are no longer working as they were initially designed (Magic Move is a good example of this). We are hoping to better separate these concerns, utilizing hooks and more succinct components.

3. We will eventually want help from the community, but we are keeping the core rewrite limited to a small in-house development team for now, just until we're stable enough for release. There's not much for the community to do just yet to support us, but we would love feedback on the new library and API when it's ready. I'll circle back to this thread when that happens. 🙂

I would love to hear any feedback you might have for us! What kind of customizations have you implemented in your fork of the boilerplate? Are there any specific rabbit holes you wish you hadn't gone down? Any specific feature requests?

[hannahhoward]

That sounds lovely overall and good directions to take! (yes I've seen the manager code and it's a doozy :)

The biggest thing I do is maintain a whole bunch of what I call slide templates -- namely, rather than write out each slide, I often want a one liner for just the content of slide styles I use a lot (simple heading on a page, heading followed by text, text followed by heading, heading-image-text, etc), plus some color changes I use a lot (my presentations often have a notion of a "regular" color scheme and an "inverted" color scheme that I use to distinguish parts of the presentation). MDX obviously could handle some of this but this way I get to really dig in on look and feel while not sacrificing speed of writing slides.

The biggest problem this presents is to preserve brevity I want these templates to behave like actual Slide components, which has neccessitated writing a terrible 300+ line higher-order component I call asSlide, which converts any template to a slide. The body is basically the entire contents of the Slide source code plus passing all the parameters to the child component properly. I can't even remember if this is entirely necessary at this point. Its terrible to maintain cause of course every time I update spectacle I have to update it to match whatever's changed in Slide.jsx. It would be awesome to have something that can truly turn custom slides into a one liner build into the framework.

Anyway, you can see my fork over at https://github.com/hannahhoward/spectacle-boilerplate - particularly the presentation/slideTemplates folder

[markerikson]

Sounds great!

I particularly like using CRA as the baseline for build setup, with Spectacle on top. I put together my own CRA+Spectacle+MDX boilerplate a while back - here's the reference repo:

https://github.com/markerikson/cra-spectacle-mdx-boilerplate

Biggest thing I remember with that is that I'm using an old outdated version of the MDX loader or something, because there were a bunch of breaking changes with the 1.0 version. Since what I had worked sufficiently, I didn't want to waste time touching it.

The biggest weakness with the MDX approach is that I've found myself wanting to mix together a custom layout, such as a code pane on the left and Markdown content on the right, but in order to do that I have to use a <Markdown> component and then write the content as a template literal in a prop. Works, but ugly, and something about the MDX parsing in there fails if there's any empty lines in that nested text. I also have to escape any inline code snippets in that Markdown. Example:

import nodeProjectLayout from "./examples/nodeProjectLayout";

#### JavaScript Project Structure

<Layout>
    <Fill style={{marginRight : 5, maxWidth: 600}}>
        <CodePane source={nodeProjectLayout} lang={"diff"} />
    </Fill>
    <Fill style={{marginLeft : 5}}>
        <Heading size={5}>Typical Project Layout</Heading>
        
        <Markdown source={`
- Run app: \`node src/server.js\`
- Node files use CommonJS module format
    - ES Module support still experimental
        `} />
    </Fill>
</Layout>

I don't expect the rewrite to necessarily have a solution for that, but FYI.

[kale-stew]

I'm going to use this issue as a landing pad for all things relevant to our rewrite. Questions, feedback, and input are all welcome!

It's important to note that all references to classic-spectacle or "old spectacle" in the following passage are talking about the existing codebase. The new API will be henceforth referred to as v6 or new-spectacle.

In our rewrite, we are aiming for as much feature parity between classic-spectacle and new-spectacle. Some components aren't going to make the parity cut as we don't want them to hinder our release. The basic functionality of the library is going to stay the same, and users will have the options to write JSX or MDX to create their presentations. We want to document a handful of feature requests that I'm hoping to carry into our new codebase, as well as some features that didn't make the cut.

To see the existing diff, check out our task/rewrite branch.

Existing Feature Requests

The following are open issues and feature requests the community has opened against classic-spectacle. We have closed all open issues in favor of using this open one to track all things rewrite.

1. Master Slide or Slide Templates (Feature Request: Master Slide / Slide Templates #529) — this is a common request, and something that we wanted to prioritize in this rewrite. This ties into a number of other open issues, and it all boils down to how we are currently handling Slide renders. Breaking this functionality out of the manager and relying on context should help resolve some of the underlying hierarchical issues with theming.
2. Vertical Slides (Vertical Slides #603) — this, among a few other requests for feature parity between Spectacle and reveal.js, is on our roadmap for v6.
3. Notes-only Mode (Notes only mode #578) — it has been requested to display only the presenter Notes that have been co-located with a given Deck.
4. Code-Slide (Feature Request: code-slide with semantic highlighting and walk-through #565) — we are handling Code slides and CodePanes differently in new-spectacle, and will be wrapping this functionality into v6.
5. Visible Menu for Control Actions (Visible menu to turn on Autoplay, Overview, Fullscreen, Print etc. #585) — for shareable presentations, it would be nice to have an easy-to-spot menu of control actions for those unfamiliar with the presentation's hot keys.
6. API for Control Actions (API for control actions #521) — another nice-to-have for advanced remote control over your presentation.

Soon-to-be-Deprecated Features

There are also a few components that we are willfully deprecating and, unless they are re-requested, will not be reintroducing to new-spectacle anytime soon. This isn't to say that we aren't accepting community contributions or feature requests for any of the following components, simply that they weren't a high-priority for us to release v6.

• The Clock component is going away.
• MagicMove isn't coming back anytime soon, but we are accepting any attempts the community might want to make at wiring it up. 🙂
• Fit and Fill are being deprecated in favor of an improved out-of-the-box styling approach.
• Same goes for Table and all of its sub-components (TableBody, TableHeader, TableItem, TableRow).
• MarkdownSlides is another component that will not be high-priority to reintroduce.

[kale-stew]

@markerikson thank you for bringing this up! Our current approach to MDX is definitely brittle, and we've prioritized improving that user experience first and foremost. I think you'll be pleasantly surprised with the new API, given your issue is primarily with styling MDX slides. 🙂