Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

convert DOM creation/manipuation code to concise Solid JSX #1716

Draft
wants to merge 7 commits into
base: develop
Choose a base branch
from

Conversation

trusktr
Copy link
Member

@trusktr trusktr commented Jan 7, 2022

Summary

  • This converts Docsify's internal string-based DOM code (f.e. creation of DOM elements, usages of innerHTML, etc) to Solid JSX and Solid function components. See commits for more info.
  • The goal for this PR is to be 100% backwards compatible, and this will be only an implementation detail to make Docsify's internal DOM manipulation code cleaner. Additionally, this allows the future possibility of using Solid's SSR and SSG capabilities, offloading our work to the amazing people in the Solid community who specialize in SSR/SSG.
  • Using Vue (or similar component systems with unique single-file component syntaxes) instead of Solid would require a total refactor of Docsify code, making that path much more difficult. In the changes, we can see that I merely replaced some lines of code with JSX expressions, and slightly refactored the tpl functions to be Solid component functions, making this change fairly non-invasive compared to some other options.
  • This updates Rollup and replaces Buble with Babel (we're already using Babel anyway) to add babel-preset-solid for compiling Solid JSX expressions.
  • At the moment this breaks the current SSR feature, but the intent is not to.

What kind of change does this PR introduce?

Refactor

For any code change,

  • Related documentation has been updated if needed
  • Related tests have been updated or tests have been added

Does this PR introduce a breaking change? (check one)

  • Yes, but the plan is not to merge this until it does not. (Draft PR until then, or maybe never)
  • No

If yes, please describe the impact and migration path for existing applications:

Related issue, if any:

Tested in the following browsers:

  • Chrome
  • Firefox
  • Safari
  • Edge
  • IE

This updates Rollup and replaces Buble with Babel (we're already using Babel anyway) to add babel-preset-solid for compiling Solid JSX expressions.

At the moment this breaks the current SSR feature.
@vercel
Copy link

vercel bot commented Jan 7, 2022

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/docsify-core/docsify-preview/GryAvaaNEjaykBNEpNqJ8wYWosZd
✅ Preview: https://docsify-preview-git-dom-with-solid-docsify-core.vercel.app

@codesandbox-ci
Copy link

codesandbox-ci bot commented Jan 7, 2022

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 9658ed4:

Sandbox Source
docsify-template Configuration

We had to pin the `colors` library (used by live-server)because the
author wilfully broke it to disrupt millions of users.
Marak/colors.js#285
"browser-sync": "^2.26.12",
"chokidar": "^3.4.2",
"colors": "^1.4.0",
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pinned because live-server depends on libraries using @latest which is a good way to get breaking changes into projects, including this one: Marak/colors.js#285

"jest-image-snapshot": "^4.2.0",
"jest-playwright-preset": "^1.4.1",
"jest-playwright-preset": "^1.7.0",
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updating Jest dependencies seems to have somehow causes jest-image-snapshot to produce slightly different font rendering, requiring an update to one of our visual snapshots.

I verified locally that both develop and this branch look identical by alternating between tabs in Chrome, and we can also verify this using Vercel's preview.

@@ -1,7 +1,7 @@
// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`Docs Site coverpage renders and is unchanged 1`] = `
"<section class=\\"cover show\\" style=\\"background: linear-gradient(to left bottom, hsl(127, 100%, 85%) 0%,hsl(127, 100%, 85%) 100%)\\"><div class=\\"mask\\"></div><div class=\\"cover-main\\"><p><img src=\\"http://127.0.0.1:3001/_media/icon.svg\\" data-origin=\\"_media/icon.svg\\" alt=\\"logo\\"></p><h1 id=\\"docsify-4122\\"><a href=\\"#/?id=docsify-4122\\" data-id=\\"docsify-4122\\" class=\\"anchor\\"><span>docsify <small>4.12.2</small></span></a></h1><blockquote>
"<section class=\\"cover show\\" style=\\"\\"><div class=\\"mask\\"></div><div class=\\"cover-main\\"><p><img src=\\"http://127.0.0.1:3001/_media/icon.svg\\" data-origin=\\"_media/icon.svg\\" alt=\\"logo\\"></p><h1 id=\\"docsify-4122\\"><a href=\\"#/?id=docsify-4122\\" data-id=\\"docsify-4122\\" class=\\"anchor\\"><span>docsify <small>4.12.2</small></span></a></h1><blockquote>
<p>A magical documentation site generator.</p></blockquote>
<ul><li>Simple and lightweight</li><li>No statically built html files</li><li>Multiple themes</li></ul><p><a href=\\"https://github.com/docsifyjs/docsify/\\" target=\\"_blank\\" rel=\\"noopener\\">GitHub</a>
<a href=\\"#/?id=docsify\\">Getting Started</a></p></div></section>"
Copy link
Member Author

@trusktr trusktr Jan 10, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As noted in some comments in the test specs (see comments containing JEST_JSDOM_BUG), this snapshot had to be updated because jsdom presents an empty style attribute despite that it is not (this is a bug in jsdom).

Generally we must avoid updating snapshots at all costs, because this can me we are allowing breaking changes into someone's CSS code of visual expectations. In this case no harm is done because I verified that the style attributes work as intended in a real browser environment, but because of jsdom's bug, I can't write a test for it in integration or unit tests. Perhaps I can write an e2e test instead, but I'm still working on fixing some e2e tests.

{config.coverpage && <Cover />}
<Main {...config} />
</>
);
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

By converting to Solid components, like this example, we will eventually be able to allow end users to provide their own component in order to override Docsify's, allowing them to make their own Docsify templates.

This will vastly improve Docsify's theme-ability: not only can they override CSS like currently (f.e. docsify-themeable being the most notable example), but they will also be able to replace the DOM structure that wraps the markdown output.

@@ -26,7 +28,7 @@ export default function(color) {
}

get(href).then(res => {
const style = dom.create('style', res);
const style = <style>{res}</style>;
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👀

Playwright had some in-range breaking changes (regressions): microsoft/playwright#10819 and microsoft/playwright#11570

Playwright tests need to `await onceRendered()` after each route navigation to wait for render to finish before testing the state of the rendered DOM. Tests were flaky because they were looking for DOM before render finished (sometimes).

Additionally, this fixes one test that was failing only locally, but not in CI, due to a RegExp check against page.url() (not sure why it would differ on CI vs local, but now the URL is explicit).
@jhildenbiddle
Copy link
Member

jhildenbiddle commented Feb 5, 2022

@trusktr --

Before too much time is spent integrating SolidJS, I think it's worth getting buy-in from @docsifyjs/core.

Some maintainers have already expressed concerns and a desire to better understand the pros and cons of SolidJS vs. alternatives. To give just one example, I think it's worth considering how and why a project like Astro remains framework-agnostic while providing official support for rendering pages using React, Preact, Svelte, Alpine, Vue, SolidJS (!), and vanilla JavaScript. Given the come-and-go nature of JavaScript frameworks and, realistically, the adoption of SolidJS compared to more popular frameworks, this seems like a more future-proof approach for Docsify that still provides the SolidJS support you're hoping to achieve. We don't need to have the discussion in this PR, but it's one I believe is worth having before we green light the adoption of any framework for Docsify.

My goal is to avoid potential issues down the road if/when this work is completed and you receive pushback instead of appreciation for the efforts you've made. It's the same reason why we recommend in our PR request template that contributors create an issue, discuss, and wait for approval before creating a PR:

To avoid wasting your time, it's best to open a **feature request issue** first and wait for approval before working on it.

I also want to make sure smaller, seemingly innocuous changes aren't used as justification for larger and more significant changes down the road. I'm not saying that is what's happening here, but it's easy to imagine how "but we're already using SolidJS" could be used as an argument in future discussions.

As I've mentioned before, I have no issues with SolidJS specifically or the improvements your proposing (framework discussions aside). Maybe SolidJS is what we'll end up with. Maybe not. I just want us all to be well-informed so we can make the best decisions for Docsify long-term.

Happy to continue the discussion in a separate issue and see where we land.

@trusktr trusktr changed the title convert some DOM creation code to Solid JSX convert DOM creation/manipuation code to concise Solid JSX Jun 30, 2023
@trusktr trusktr mentioned this pull request Jun 30, 2023
17 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants