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

[WIP] feat(docs):Addition of JS/TS Toggle button in the docs to switch to appropriate code. #3082

Closed
wants to merge 11 commits into from

Conversation

noopurphalak
Copy link

@noopurphalak noopurphalak commented May 10, 2023

Before submitting the PR, please make sure you do the following

  • Read the Contributing Guidelines.
  • Read the Pull Request Guidelines.
  • Check that there isn't already a PR that solves the problem the same way to avoid creating a duplicate.
  • Provide a description in this PR that addresses what the PR is solving, or reference the issue that it solves (e.g. fixes #123).
  • Ideally, include relevant tests that fail without this PR but pass with it.
⚠️ Slowing down new functions

Warning: Slowing down new functions

As the VueUse audience continues to grow, we have been inundated with an overwhelming number of feature requests and pull requests. As a result, maintaining the project has become increasingly challenging and has stretched our capacity to its limits. As such, in the near future, we may need to slow down our acceptance of new features and prioritize the stability and quality of existing functions. Please note that new features for VueUse may not be accepted at this time. If you have any new ideas, we suggest that you first incorporate them into your own codebase, iterate on them to suit your needs, and assess their generalizability. If you strongly believe that your ideas are beneficial to the community, you may submit a pull request along with your use cases, and we would be happy to review and discuss them. Thank you for your understanding.


Description

Resolves #2475

Additional context

This PR introduces a toggle for JS/TS switch on every function page in the vueuse documentation.

This PR is still work in progress, I will mark it for review as soon as it is ready for review.


🤖 Generated by Copilot at 425a218

This pull request adds a feature to the documentation site that allows users to switch between TypeScript and JavaScript code examples. It introduces a new dependency @vue/theme and a new component TsJsToggleSwitch.vue for the sidebar toggle. It also updates the documentation page for createGlobalState and the pnpm-lock.yaml file.

🤖 Generated by Copilot at 425a218

  • Add the @vue/theme dependency to enable a custom theme for the Vitepress documentation site (link, link, link)
  • Import and use the TsJsToggleSwitch component to render a language preference switch in the sidebar (link, link, link, link, link)
  • Add <div class="js-api"> and <div class="ts-api"> tags to the documentation pages to toggle the visibility of JavaScript and TypeScript code examples (link, link)
  • Remove the dev: true property from several dependencies in the lock file that are also used for production (link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link, link)
  • Update the body-scroll-lock dependency to version 4.0.0-beta.0 and add version 3.1.5 as a dependency of the @vue/theme package (link)
  • Add the normalize.css dependency to the @vue/theme package and remove it from the dev: true dependencies (link, link)
  • Remove an empty line from the createGlobalState documentation page for readability (link)

@noopurphalak noopurphalak changed the title [WIP] Addition of JS/TS Toggle button in the docs to switch to appropriate code. [WIP] docs:Addition of JS/TS Toggle button in the docs to switch to appropriate code. May 10, 2023
@noopurphalak
Copy link
Author

noopurphalak commented May 10, 2023

@antfu I have create a toggle button on the top of the sidebar in this PR. The PR is still in progress as now I have to write all the switchable content for all the functions. I wanted some clarification from you on some thing.

In the PR, I have written the typescript code snippet for createGlobalState as follows:

// store.ts
import { ref } from 'vue'
import { createGlobalState } from '@vueuse/core'
export const useGlobalState = createGlobalState(
  () => {
    const count = ref(0)
    return { count }
  }
)

This is same as the javascript code. This is because all the types are already inferred from the createGlobalState function in the output. Is this okay? Or should I write the function as below:

// store.ts
import { ref } from 'vue'
import { createGlobalState } from '@vueuse/core'

function storageFn() {
    const count = ref(0)
    return { count }
}
export const useGlobalState = createGlobalState<typeof storageFn>(storageFn)

Also request you to take a look at the toggle component I made for toggling the code i.e. TsJsToggleSwitch.vue. I have implemented it exactly as the api preference switch in vuejs documentation. I am not really an expert in CSS, but I have done the best I could.

@noopurphalak noopurphalak changed the title [WIP] docs:Addition of JS/TS Toggle button in the docs to switch to appropriate code. [WIP] feat(docs):Addition of JS/TS Toggle button in the docs to switch to appropriate code. May 10, 2023
@antfu
Copy link
Member

antfu commented May 11, 2023

Thanks!

I think we should not manually write js/ts docs version at all, to avoid increasing the maintenance burden.

Instead, as I suggested (#2475 (comment)), we should always write in TS, and use a custom plugin to generate the js version from the ts blocks using esbuild at compile time

@noopurphalak
Copy link
Author

noopurphalak commented May 11, 2023

Thanks for your reply @antfu . Can you also tell me which of the above typescript code snippets should I use for createGlobalState function?

@noopurphalak
Copy link
Author

Hey @antfu , As suggested by you, I have created a plugin that will create a JS frame for the typescript snippet it finds in all the index.md files. Can you review it once? I can then change the JS snippets in every function to show typescript by default and they can be transpiled to JS frames on build time?

@sxzz sxzz marked this pull request as draft May 12, 2023 13:14
@noopurphalak
Copy link
Author

@antfu Request you to please check if the plugin I created for typescript transpilation to javascript is what we require? I can then move ahead with converting code snippets to typescript for other functions...

@@ -11,19 +11,24 @@ Keep states in the global scope to be reusable across Vue instances.

### Without Persistence (Store in Memory)

```js
// store.js
<div class="ts-api">
Copy link
Member

@antfu antfu May 16, 2023

Choose a reason for hiding this comment

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

Can we automatically apply the transformation to any ts blocks, without the need of this marker? (so the documents keep untouched)

Copy link
Author

Choose a reason for hiding this comment

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

the <div class="ts-api">...</div> and <div class="js-api">...</div> are identifier classes for when to hide which code block when the toggle is used.

Please refer the below code in TsJsToggleSwitch.vue:

https://github.com/vueuse/vueuse/pull/3082/files#diff-8ac7c8298153b8b006a414a6ff0abde634bd9a6483eec29d42ad4387981aa170R174-R184

What TsJsToggleSwitch.vue does is, the default code enabled is the Typescript code, when we toggle to Javascript, the component adds a prefer-js class to the body. Once this class is attached to the body, the typescript code (one with class ts-api) gets a display: none; css property and the Javascript code (one with class js-api) gets a display: initial; css property. Similarly, when you toggle it back to typescript, the Javascript code gets removed from the DOM and the Typescript code gets added back to the DOM. Hence the div elements in the documents.

I have also written a vite plugin tsToJsTransform.ts, which recognizes the typescript code using the divs with the ts-api and transpiles the code inside it to Javascript code and adds both the snippets in the file code at build time. Correct me if I am wrong, but we are supposed to rewrite all the JS snippets as TS snippets and transpile those snippets on build time to generate an additional JS code block.

If you have a better approach, please let me know, and I shall try to go that way.

Copy link
Author

Choose a reason for hiding this comment

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

@antfu Please let me know if you have a better approach...

Copy link
Author

Choose a reason for hiding this comment

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

@antfu Can you please update on my comment?

@stale
Copy link

stale bot commented Jul 31, 2023

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

@stale stale bot added the stale label Jul 31, 2023
@stale stale bot closed this Aug 7, 2023
@antfu antfu removed the stale label Sep 3, 2023
@antfu antfu reopened this Sep 3, 2023
antfu added a commit that referenced this pull request Sep 4, 2023
Copy link

stale bot commented Dec 6, 2023

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

@stale stale bot added the stale label Dec 6, 2023
@stale stale bot closed this Dec 14, 2023
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.

Documentation should include a toggle for javascript/typescript
2 participants