Line Annotations

[karlhorky]

Hi! First of all, thanks for this great project! It's super useful.

I'm creating teaching materials (course material) with this tool, and I would like to annotate certain parts of the source code with arrows, indicators, labels and other diagram elements that are not in monospace font (see examples below) - some similarities to LaTeX brackets / parentheses / braces. I tried to use the current APIs, but I didn't get very far.

I ended up creating an MVP solution (described below) and I wanted to get feedback on it :)

TODO

• add a slide to the sample deck

Ideal Examples

Current MVP Solution

In order to do the very minimum of implementation work with the largest impact, I have created an MVP for only line annotations that allows for strings and React components to be passed via a new property called lineAnnotations in the step object, which is an object mapping lines to their annotation content.

The MVP is currently published under @upleveled/mdx-deck-code-surfer@0.6.3 (depends on @upleveled/code-surfer@0.6.1).

To try it out:

yarn add --dev @upleveled/mdx-deck-code-surfer

It allows for things like this:

via this code:

<CodeSurfer
  title="Example of HTML code"
  code={require('!raw-loader!./first-example.html')}
  lang="markup"
  steps={[
    {},
    {
      lineAnnotations: {
        4: (
          <span style={{ fontFamily: 'BlinkMacSystemFont' }}>
            {' '}
            <Arrow
              angle={270}
              length={300}
              style={{
                verticalAlign: '-4px',
                width: '300px',
              }}
              color="white"
            /> Opening Tag
          </span>
        ),
        6: (
          <span style={{ fontFamily: 'BlinkMacSystemFont' }}>
            {' '}
            <Arrow
              angle={270}
              length={292}
              style={{
                verticalAlign: '-4px',
                width: '292px',
              }}
              color="white"
            /> Closing Tag
          </span>
        ),
      },
    },
  ]}
/>

---

What are your opinions of this API?

More specifically:

1. Do you have any recommendations on a better way to achieve what I'm intending here?
2. Should I use Scroller.Element at all?
3. Should this API be more generalized? More like:

interface Step {
  annotations?: {
    lines?: {
      [key: number]: JSX.Element | string
    }
  }
}

4. Should I update the step-parser.js test file?

[pomber]

Yes! I'd love to have some kind of line annotations. They are much better than notes.
Could you add a slide to the sample deck in the PR so we can see it in action?

I don't have anwsers for your questions yet. I'm focusing on another project right now. I'll come back to code-surfer soon (in a few weeks) 'cause I need to write a talk and I want to rewrite a big part of this project to support new features.

[karlhorky]

Great, glad that the feature is also valuable for others!

Could you add a slide to the sample deck in the PR so we can see it in action?

Sure, I've added a TODO in the description. I'll do this along with any feedback that you have in a few weeks :)

[karlhorky]

I've also changed the lineAnnotations keys to be 1-based instead of 0-based, so that they match line numbers.

[karlhorky]

I'll come back to code-surfer soon (in a few weeks)

Did you have a chance to put some more thought into this?

[pomber]

Hi @karlhorky , I'm currently rewriting code surfer from scratch to support new things. Line annotations is one of those things I want to support. I'm keeping this PR open as a reference.
Thanks for your patience

[karlhorky]

Ok, if you're reimplementing this feature, I may be able to be of assistance. Maybe it would make sense to make it more general and easier to work with. For example, general annotations for anything? Maybe with a default style for the "pointer"/"tooltip" element?

[karlhorky]

Hi @pomber ! Now that v3 has dropped, do you have any insights into how such a feature could be implemented there?

Would really like to do this to be able to annotate my code like in the examples above :)

[pomber]

I want to use something like annotations for blogging too.

One approach I want to try is to provide a useStepInfo() hook so any child of the step can absolute-position itself in the right place of the slide. Then, export an Annotation component that use that hook together with the lines and columns that it's annotating to show the annotation.

But I don't have the time now, it would have to wait...

[karlhorky]

Ok, so there's no way to do this at the moment, even with a more hacky solution?

I guess I'll have to wait to upgrade then... Or find some workaround...

[pomber]

For now, you could try to write your own version of this component and hardcode the annotations there for each slide. But it may be too hacky...

[karlhorky]

Ok, will take a look, maybe I can get something working. Thanks!

[karlhorky]

Hey @pomber, I didn't get a chance to try this out yet... Any news from your side on this feature?

[pomber]

Hey @pomber, I didn't get a chance to try this out yet... Any news from your side on this feature?

Hi. Not really. I'm focusing more on this other project, which eventually should replace the core of code surfer and be more flexible.

[karlhorky]

Ok thanks. I guess probably no ETA for Code Hike?

code-surfer@0.6.13 is aging not so gracefully (still requires mdx-deck@^1).

Maybe time to try to upgrade one of my decks to 3.1.1 and try to come up with a new workaround.

[karlhorky]

Ah just trying this out - unless I'm missing something I guess the new Code Surfer steps API is much less flexible :(

Maybe I move off of Code Surfer completely and try to implement my own thing using react-syntax-highlighter and useStep from mdx-deck.

[pomber]

Maybe I move off of Code Surfer completely and try to implement my own thing using react-syntax-highlighter and useStep from mdx-deck.

That may be the best alternative if you need something soon

[karlhorky]

Ok, I've opened up a followup to this in #115, maybe we can continue the discussion over there...