Generate Examples -- Continued

[trillium]

This is following on from the work of #940
Might resolve:

• create a tool to make it very easy to make snapshots of examples #1744
• Make GIF generator using existing test cases #215
• Create web page to represent test cases #866

This is currently a draft PR

• Last updated 2025-04-17

Latest updates

• Upgrade to Shiki v3
• Create reference highlight colors from colors field in package-json
• Create helper functions to create shiki compatible decorations for each interaction type
  • (not all finished)
• Update some types (still pretty messy in the current types)
• Render clipboard interactions in finalState
• Render selection interactions
• Render referenced object ineractions

ToDos Immediate

• Refactor HTMLGenerator class
• Resolve type issues
• Render line creation interactions
• Render thatMark interactions

ToDos IceBox

• Resolve CSS issues relating to block and inline-block display
• Create animation out of initialState, during, and finalState

How to test

• Navigate to /packages/cursorless-org/
• run pnpm dev
• open localhost:{PORT NUMBER}/component-sheet

Screenshots 2025-04-19

Current issues

• The during step that shows selection for deletion isn't being hit

  • Haven't updated the code to capture a pendingDeletion selection yet (loadFixtures.ts)

• Color scheme is very bad, will need to pick something better eventually

• I have added tests

• I have updated the docs and cheatsheet

• I have not broken the cheatsheet

[SimeonC]

Thanks for picking this up! If you need any help figuring out what I was doing let me know. I can answer questions but completely have no time to code outside of work commitments 😞

[trillium]

All good, happy to see you're well :)

I'm definitely curious about the decisions you made to choose these libraries and what your vision was for how you wanted this feature to end up.

Recently I was looking for more opportunities for to learn what Cursorless can do and wanted a series of gifs that could demo its capabilities. We've already got all these test files so that seemed like a good place to start, and it turns out you already are plenty of the way there!

[SimeonC]

I think we just had the same desire, while I was learning Cursorless at the start I just wanted something like a "library" of examples of what each command could do. My overall thinking was just a "search command/scope/etc, see examples" type app, but never got past the "just make the HTML work" stage.

I don't think there was anything really "deep" in my decision-making, shiki lib had the ability to give me the objects/arrays that I could manipulate like a "middleware" to add all the highlighting/tokens before rendering the HTML (bonus that it had all the different styling options too). That was really the only decision I made, the rest is all just hard work figuring out how to make overlapping ranges highlight (no multi-ranges is the easy part), hence the tests cause I broke my own code so many times trying to fix it, I suddenly had a better appreciation for TDD 🤣

[trillium]

I think one of my main questions is where this will end up residing. Eg is it gonna be available locally via something like the cheat sheet or is it only online via the docs.

That might be a better question if Andreas or Pokey, but I think it affects how I would explore building this.

My first inclination was to see if anything could be reused from the Docusaurus space:

• Use a build system to turn the test YAML files into MDX
• Create a custom component to render the MDX with all the highlight, ranges, hats info in the grey matter area

If it's going to reside in the cheat sheet then there's no established components, theme etc to start from and something like shiki seems like the right choice.

I honestly have no idea though.

[SimeonC]

Sorry can't help you there, definitely a question for Pokey or Andreas as I didn't really figure out with them where was best.

[AndreasArvidsson]

With the caveat that I haven't really read through the previous pull request we definitely want code examples in the online documentation. We might link from the cheat sheet to the online docs, but I don't think we should actually cram all the documentation into the cheat sheet itself.

[pokey]

A package is the way to go, but I'd recommend starting from a clean checkout of main and then proceeding as follows:

1. Run the steps in the docs for creating a new package (your package is a library, so don't add private in step 4)
2. Lift just the typescript files from Add the generate-examples library #940
3. Take only whatever else you need from Add the generate-examples library #940 to actually make things work. There's a lot of nx cruft in that PR that we don't need anymore

I'm not sure generate-examples is the name I'd go with. I think the primary export of this package should be a react component whose input is a TestCaseFixture. So I think I'd maybe call the package test-case-component? @AndreasArvidsson any thoughts on name?

Fwiw you might want to look at the cheatsheet package, as that's an example of a package whose primary export is a react component

For local testing / experimentation, I'd just add a dummy page to our cursorless-org package so you can use our next.js local dev setup. That's what we do for our cheatsheet (https://github.com/cursorless-dev/cursorless/blob/main/packages/cursorless-org/src/pages/cheatsheet.tsx; actually deployed at https://www.cursorless.org/cheatsheet fwiw) You can just use a dummy fixture for now. See README at https://github.com/cursorless-dev/cursorless/tree/main/packages/cursorless-org for info on how to run local dev server

Once you have a working react component, we can look into getting it into docusaurus using mdx

Lmk if any of the above doesn't make sense, and feel free to drop into another meet-up if you get stuck!

[trillium]

I wanted to keep the commit record from @SimeonC if possible so I reconfigured a few things and it should be working properly. The code still builds in the same way it use to.

Still working on getting a test page to render similar to cheatsheet

[pokey]

ok no worries; looks like you managed to remove all the unnecessary nx stuff so that's fine 👍. I'd move all the lib/ stuff up to src/ dir tho; that lib subdir isn't a pattern we follow

[trillium]

Moved files from src/lib/* to src/*

Though, that same pattern is in packages/cheatsheet/, but it's literally the only one

# find . -type d
./cheatsheet
./cheatsheet/node_modules
./cheatsheet/node_modules/@types
./cheatsheet/node_modules/.bin
./cheatsheet/node_modules/@fortawesome
./cheatsheet/node_modules/@testing-library
./cheatsheet/src
./cheatsheet/src/lib
./cheatsheet/src/lib/components
./cheatsheet/src/lib/sampleSpokenFormInfos
./cheatsheet/src/lib/hooks

[pokey]

Oh interesting. I wonder why we do that there. Probably same reason tbh; was migrated from the old nx semi-mono-repo and never changed

[trillium]

I've been working on mirroring the format of the cheatsheet for a componentsheet, I currently am getting stuck at module/types import from @cursorless/test-case-component but I think it's because I don't understand how to generate types for the test-case-component module.

I was also having a few issues just trying to understand how everything worked together by running cursorless-org pnpm dev and editing text in packages/cheatsheet/src/cheatsheet.tsx to see how changes propagated

I couldn't get anything to change e.g.:

• edit packages/cheatsheet/src/cheatsheet.tsx
  • change h1 to Testy test Cursorless Cheatsheet
  • wait for next to confirm rebuild
  • see no changes on localhost:3000/cheatsheet

[pokey]

I've been working on mirroring the format of the cheatsheet for a componentsheet, I currently am getting stuck at module/types import from @cursorless/test-case-component but I think it's because I don't understand how to generate types for the test-case-component module.

could you possibly elaborate? not sure I follow

I was also having a few issues just trying to understand how everything worked together by running cursorless-org pnpm dev and editing text in packages/cheatsheet/src/cheatsheet.tsx to see how changes propagated

I couldn't get anything to change e.g.:

* edit `packages/cheatsheet/src/cheatsheet.tsx`
  
  * change `h1` to `Testy test Cursorless Cheatsheet`
  * wait for next to confirm rebuild
  * see no changes on `localhost:3000/cheatsheet`

Strange. I could have sworn that used to work 🤔. But yes I confirmed it's not working for me either. Here's a fix #2286

[AndreasArvidsson]

I'm not sure generate-examples is the name I'd go with. I think the primary export of this package should be a react component whose input is a TestCaseFixture. So I think I'd maybe call the package test-case-component? @AndreasArvidsson any thoughts on name?

Test case component sounds good

[pokey]

fwiw #2286 now merged so hot reload should work once you do a git merge

[pokey]

I see there's a conflict in your lockfile. Generally easiest to just revert the lockfile to main and then do a pnpm install

[trillium]

Haven't made that much progress on this since last check in. Got content to render from packages/test-case-component just now though so that's progress!

I do my best to copy the cheatsheet page format from existing code to where applicable to test-case-component
Actions thusfar:

• Add dependency test-case-component to cursorless-org copying cheatsheet's format
• Create a text-case-component.tsx file for initial workings
  • Experiencing an error

import {
  TestCaseComponentPage
} from "@cursorless/test-case-component";
//              ~~~~~~~~~~~~~~~~~~~~~~~~~
import Head from "next/head";

// Cannot find module '@cursorless/test-case-component' or its corresponding type declarations.

I originally thought this was blocking me from getting the test-component-sheet page to render but that isn't blocking me any longer.

[trillium]

Thanks for taking some extra time before you all hopped off todays call :)

Notes

cursorless-org/component-sheet page

• get yaml coming into component
• hardcode ok for now
• pass as props
• can add a yaml dependency if needed
  • of type TestCaseFixture
    • let it be type:any for now
• okay to stick with Jest if needed
  • cheatsheet might use Jest?

Test file

• try to get tests to run before making any changes to structure
• Cursorless uses Mocha for most tests
• okay to stick with Jest if needed
  • cheatsheet might use Jest?

[pokey]

can add a yaml dependency if needed

* of type TestCaseFixture
  
  * let it be type:any for now

just to clarify this one: TestCaseComponent should declare the property type as TestCaseFixture, but in the TestCasePage in cursorless-org you should leave it as type any. Make sense?

[trillium]

Yes that makes sense

• Page should import the yaml but not care about the type
  • pass to Component as props
• Component should care about the type to prevent errors

[trillium]

Back to working on this after a looooooong hiatus.

Screenshots