Adopt twoslash for docs

[AndreyYolkin]

As one of the aims of radashi is better Typescript support, we can highlight it better with twoslash integration, available by brand-new community plugin https://github.com/MatthiesenXYZ/EC-Plugins/tree/main/packages/twoslash, which is a twoslash wrapper for Expressive Code, used in Astro.

I've tried to adopt some examples and how it may look like:

_.assign

_.castArray

_.first (we can discuss the proper naming)

The best part is that types are picked from code automatically and we don't need to specify any additional data (only mocks, like in _.all examples)

[aleclarson]

Love it. Does twoslash get loaded after first paint?

[AndreyYolkin]

I think, i can make a custom build and provide a link with some examples with twoslash enabled

[AndreyYolkin]

UPD: we are live
Check the examples at https://luminous-elf-a6e4e4.netlify.app/ from alphabetical to fork is ready, more to come if we decide that's useful

[aleclarson]

Sweet. I think it's a worthy feature. PR welcome :)

[Adammatthiesen]

Hey @AndreyYolkin Thanks for supporting my project (Expressive-code-twoslash)!

Currently working on rolling out a nice feature update(bringing more of twoslash into EC) as well as some huge code cleanup, the JS module mentioned is handling hiding and showing the popups using a unique ID system so that the hidden popups don't cause any screen reader issues, as the current goal is to not only bring Twoslash to EC, but to also add accessibility into Twoslash rendering, since this is a custom implementation based on the Shiki-twoslash and not a direct wrapper of the shiki version

[AndreyYolkin]

Hey, @Adammatthiesen, and thanks for coming, I saw a great opportunity to touch the technologies that were on my radar.

I see that radashi uses patched version of starlight, imported as git submodule. I think I will open another proposal to utilise pnpm's ability to patch package (with https://github.com/antfu/pnpm-patch-i it has a better DX as well) and maintain only patch instead of almost a fork of starlight repo. Once this is done, it will be easier for the docs to be up to date.

I suppose that by the time I manage how to do contributions easier for other developers you also made the things you mentioned (I saw that this repo is almost a week old, but found that it's already in great condition).

[AndreyYolkin]

I'm making a progress with translation, still there are some questions:

1. I needed to tweak .npmrc with shamefully-hoist=true to complete installation with pnpm. I will think later about committing lockfile, maybe the instruction in README is not exhaustive enough, as simple copy-pasting didn't work.
2. Sometimes like in defer example we will need to define fake functions in order to make twoslash show types. I think this is better than just leave the code section without twoslash

Render:

MDX:

3. Although there are still some scenarios where it's hard to define even mocks, like code extracted from lodash library. I decided to leave this code as-is, but we may reconsider it in a future.

4. (Opinionated) I propose to add as const to data mocks, to illustrate type-narrowing in radashi even better OR include both options

Array.First:

Array.First(with as const):

5. AFAIU there will be two PR's: for website docs and for radashi docs. I can open PR to the website builder now, as it's almost ready (except p.1) and draft PR to the docs examples

[AndreyYolkin]

@aleclarson sorry for pinging, I need my thoughts to be validated + decision for p. 4 in order to continue adopting twoslash. I will be grateful if you can review and make a comments about 🙂

[aleclarson]

@AndreyYolkin The ping was 100% warranted. Sorry to leave you hanging!

We're agreed on points 2, 3, and 4. 👍

Probably best to do only as const, instead of having examples with and without; just to keep the number of examples at a manageable level. Hopefully the as const assertions don't confuse the TypeScript newbies too much.

AFAIU there will be two PR's: for website docs and for radashi docs. I can open PR to the website builder now, as it's almost ready (except p.1) and draft PR to the docs examples

Makes sense to me! Your work on this is very much appreciated 🙂

I needed to tweak .npmrc with shamefully-hoist=true to complete installation with pnpm. I will think later about committing lockfile, maybe the instruction in README is not exhaustive enough, as simple copy-pasting didn't work.

You're referring to the instructions here, right?

I just tested them and got this error when running pnpm dev. Everything before that seemed to work. If this can be fixed without shamefully-hoist, that would be ideal. But since you have a workaround, we can address the issue later.

[vite] Error when evaluating SSR module /starlight/packages/starlight/index.ts: failed to import "@astrojs/mdx"
|- Error: Cannot find module '@astrojs/mdx' imported from '/Users/alec/dev/sandbox/radashi-org.github.io/starlight/packages/starlight/index.ts'

[AndreyYolkin]

+1 on that error, I followed the steps you provided and got the same error, that's why I ended with hoisting. I'll try to find a way better than this later. Back to the grind!