Mdx-deck: v2 Roadmap

[jxnblk]

This is a placeholder for potential major changes in the next version

• Split PDF export into a separate, optional package #157
• Refactor & simplify components codebase
• Handle focus trapping #93
• New UI for presenting and modes, including touchscreen UI #6
• Update layout styles, simplifying custom layout components

[jamischarles]

Would love the ability to easily combine layouts like:

---
export Split,Invert

# Heading
---

or something similar

[signalwerk]

• Multiple themes per deck ((deck with two kind of slides))
• Video-Component ((make it pop 🦄))

[jxnblk]

Video-Component

See #4 – this could be added before v2 as a non-breaking change

Multiple themes per deck

Currently this is handled with slide layouts – do you have something different in mind API-wise?

[QuentinRoy]

Something I would love is an advanced form of Appear that would give me great control on what happens on each step (i.e. not necessarily making a component appear, but anything really).

My main use case is the control of D3.js updates, like filtering some data on a step, highlighting one particular bar, etc.

For example, I would be happy with just a Higher Order Component of the form:

import withSteps from 'mdx-deck/with-steps'

withSteps(numberOfSteps, ({ step }) => {
  // Render something using step.
  return <span>Current step: {step}</span>
})

The above is just a functional component, but withSteps would also allow relying on componentDidUpdate to perform some low-level DOM operations, like updating a D3 chart:

import withSteps from 'mdx-deck/with-steps'

withSteps(numberOfSteps, class Chart extends React.Component {
  constructor(props) {
    super(props)
    this.svgNode = React.createRef()
  }
  componentDidUpdate() {
    const { step, data } = this.props
    updateChart(this.svgNode.current, data, step)
  }
  render() {
    return <svg ref={this.svgNode} />
  }
})

[signalwerk]

Currently this is handled with slide layouts – do you have something different in mind API-wise?

As far as I understand is the API for a themes and for a layout different. so I can not mix that. right? I can not pass in a theme as a layout but have to rebuild it from scratch as a layout.

[iamstarkov]

I have two points:

• it would be nice to utilise default mdx/loader
• extract mdx-deck as a standalone package for easier integration into other frameworks (CRA, next)

[zcei]

@QuentinRoy I built kinda something like this when playing around with "one slide per step" PDF export.

Currently looks like this, steps are derived from whether the a component constructor calls setSteps (current behavior, abstraction could be better)

// Simple Appear, internally using steps
<ul>
  <Appear>
    <li>One</li>
    <li>Two</li>
    <li>Three</li>
    <li>Four</li>
  </Appear>
</ul>

// Using the `AppearComponent` directly
<Steps>
  {({ step, setSteps }) => {
    return (
      <ul>
        <AppearComponent step={step} setSteps={setSteps}>
          <li>One</li>
          <li>Two</li>
          <li>Three</li>
          <li>Four</li>
        </AppearComponent>
      </ul>
    )
  }}
</Steps>

---

is this something wanted? (cc: @jxnblk) I could make a PR out of it easily, but would like to discuss some state management concept, which would be subject to "Refactor & simplify components codebase"

[QuentinRoy]

@zcei It would indeed enable my use case. Does <Step> also accept class components as child (and still give them step and setSteps as argument)? If not that means a sub component needs to be created if one want to have access to componentDidUpdate. It is OK, but I think it would be nicer if we don't need to do this.

Something that bothers me a bit, however, is having setSteps as an argument. That implies it can it be called by the subcomponent multiple time. From what I have seen in the code, it seems that would require significant change (maybe that is what your refactor is about).
Also, it is a bit unclear what would happen if setSteps is called with a value lesser than the current step. Would mdx-deck switch to the next slide?
These are the reasons I thought a Higher Order Component would be easier. It seems it can be implemented in a few line of codes. Though I agree that it requires a bit more React mastery from users.

[zcei]

The problem I saw with the HOC is that it requires mdx to understand any arbitrary JS. As far as I know it only looks at import & export statements plus the < JSX indicator.
So one would always need to move that code out of the presentation into its own file.

The componentDidUpdate thing is something I have to look into, did not consider it for the PDF export.

Yes, my refactor is about setSteps (or better the metadata management in itself). It should accept multiple components having steps, basically adding up the individual step counts to a total amount. How that would exactly looks like: don't know yet.
In general it's about the question whether the user should explicitly define the number of steps or it should be derived from the components on that slide. Open for discussion 🙂

[QuentinRoy]

Ah! Good point. I didn't thought about that.

I believe setSteps can only be derived automatically in the case of adding elements (which I think is already pretty well done by <Appear>). But my use case requires more than that. What if elements shouldn't be added but replaced, or what if something else needs to be done using the step argument (e.g., again, updating a D3 chart)?

[zcei]

I believe setSteps can only be derived automatically in the case of adding elements

Yes, that's why I exposed it, as a lot of use-cases won't have this luxury.

What if elements shouldn't be added but replaced, or what if something else needs to be done using the step argument

I think then you need a component that in the contructor sets the steps and if necessary during the lifetime it would call setSteps again to update it current totals? 🤔 This way we would definitely need to store the steps per component in the state, so that it can later be updated.

Would you know the exact steps up front for D3 stuff? And do you trigger the next step by yourself, or should D3 say that the next step starts by emitting some event? Just trying to get a solid understanding of different use-cases.

[QuentinRoy]

Would you know the exact steps up front for D3 stuff?

Yes. In my case I would always know. Maybe there is cases where you do not but, I do not have any in mind..

And do you trigger the next step by yourself, or should D3 say that the next step starts by emitting some event?

No in my use case I want to trigger the even myself. This being said, having and API to programmatically change step would be interesting as well. But I think that is something else.

[jxnblk]

Would you mind opening another issue related to a render prop based API for Appear? I want to make sure the thoughts related to that don't get lost

[QuentinRoy]

Done, see #193. I tried to briefly summarize the discussion.

[mrcasablr]

Would like the placement of content in Layout like it gitpitch snaplayouts - https://medium.com/@gitpitch/snap-layouts-for-gitpitch-markdown-presentations-29800f642586

As you already captured, layouts could use more love.

[borekb]

I'd also like more flexibility & polish around styles (typography, colors), for example:

• Nested lists are not really usable in v1 (#198).
• The themes should probably never use pure black (#000) but some sort of dark gray.
• It would be useful to have styles for subdued texts, or highlighted texts. (I found it quite difficult to customize font color for certain parts of the text, see #249, but maybe I wouldn't have a need to if this common color variations would be supported out of the box.)

[jxnblk]

The themes should probably never use pure black

For presenting on a projector, you generally do want "pure black" (and generally higher contrast) because of the nature of projectors

[borekb]

@jxnblk Probably a valid point, though I _think_ that PowerPoint, Google Slides and similar don't use pure black. Need to do a bit more research when I have time.

[jxnblk]

Just published v2 beta, which should resolve some of the things mentioned here. Feel free to open other new issues with any additional feature requests

[iamstarkov]

@jxnblk can you update either CHANGELOG.md or GitHub releases with more details about what has been released?