solidjs / solid-docs-next Goto Github PK
View Code? Open in Web Editor NEWSolidJS Docs.
Home Page: https://docs.solidjs.com/
SolidJS Docs.
Home Page: https://docs.solidjs.com/
I figured there are some minor issues with color accessibility (the white text on light blue background for active items in the menu does not clear every accessibility test for example). There are also things that are hard to read in the nav bar mainly because of spacing and separators issues. I created a Figma file with prototypes in hope to fix some of the issues. I didnโt changed any of the structure so the changes will not introduce breaking changes (mainly padding and colors fixes). I believe the docs use tailwind so I used their colors to allow a quick implementation.
I think having a beautiful doc will help solid attract more and more people and would love to be part of that. I can start working on a PR to implement these modifications, but everyone can copy the Figma file and make their own modifications !
A step-by-step guide to building and deploying your Solid app. This will include "one-click" deployment options like Vercel and Netlify, GitHub pages, and more full-fledged production environments.
@davedbase can decide if Netlify gets a special/higher mention in this doc ๐
CONTRIBUTING.md
will describe our workflow and governance, and explain how to get started.
WRITING.md
will explain our teaching philosophy, tone and accessibility requirements, and terminology.
As suggested by @ryansolid in this twitter thread i'm opening this issue here on the docs.
We should document the behavior described in the twitter thread and in this SolidJS playground (https://playground.solidjs.com/?hash=667502849&version=1.4.1). I'm gonna rewrite the issue here.
If you try to set the same value for a signal it will smartly not rerun the effects associated with that signal. However this create a problem with the input if you try to programmatically limit the values.
This is because normally the input get's updated with the new value by the browser and later SolidJS re-update the value running the effect that keep in sync the value with the signal.
But as we stated if the value does not change the effect does not run again so the "browser wins".
You can "fix" this by specifing an equal function for the signal that always returns false (at the cost of a bit of performance).
I could work on this but i really don't know when so for the moment i'm just leaving this there.
Some <nav>
elements have the redundant role="navigation"
attribute, which can lead to bugs in some screen readers and/or browsers. Also, we are currently using aria-label="Docs header navigation"
, this means that screen readers are reading this section like "Docs header navigation, navigation landmark" (tested in NVDA).
This is a quick fix that I have a PR ready to publish.
When visiting the docs for the first time (or in Incognito) with a browser that prefers dark color schemes, the page correctly uses the dark theme, but the toggle button/icon does not. You'd have to click the button twice to switch to the light theme.
I believe this is caused by the theme toggle button depending on the mode
property in the config context which is initially set to "none"
, since the button/icon only assumes the page is dark when config().mode
is set to "dark"
.
A possible solution for this would be to initially set config().mode
to either "light"
or "dark"
only instead of "none"
, depending on the browser's preferred color scheme.
On smaller screens (or when the number of sections/sections items increases) when you start scrolling you can see this bug:
Also, the current sidebar is following this semantic hierarchy structure:
h1 - Solid Docs header
h1 - Tutorials
--- h3 - Getting Started with Solid
The expected structure, that gives screen readers the best idea of the content organization would be:
h1 - Solid Docs header
-- h2 - Tutorials
--- h3 - Getting Started with Solid
This way, a screen reader user can easily navigate between the Solid Docs header link and the main content heading and also easily navigate between the upmost subsections of the page main content and the navbar upmost sections using heading shortcuts.
These are small problems that I have a PR ready fixing them.
The <NavLink>
component from solid-app-router
is marking the Docs Header as the current page (aria-current="page") in all pages, not only docs.solidjs.com
(expected behavior). Here's the current behavior and what would be expected or not:
docs.solidjs.com
-> Docs Header is the current page โ
docs.solidjs.com/tutorials/getting-started-with-solid/welcome
-> Docs Header is the current page โ Welcome link is the current page โ
Fortunately, we can fix this by adding the end={true}
prop to NavLink. I have a PR ready with the fix.
Description
Let me start by saying fantastic job on the new docs page. It covers many more topics to get started with solid that a lot of people will find very helpful.
As promised my daily issue with the new docs page.
Assumes knowledge of the core framework. Teaches how to build an SPA and why Solid Start makes that easier.
Covers:
Ideally, this is an interactive tutorial that uses Vite in the browser with Stackblitz. @modderme123 and @nksaraf are looking into that infrastructure.
https://docs.solidjs.com/how-to-guides/get-ready-for-solid/javascript-for-solid
When first writing modern JavaScript you might be tempted to use one of these keywords:
var, new, this, class
Then scroll down a little and it has an example with the new
keyword:
const currentYear = new Date().getFullYear();
Its confusing, why use new
after saying don't use it?
There is a subtle issue when registering an event handler on an element when using hyper dom script.
When the handler has zero arguments like onClick()
it will ever fire while this is not a problem onClick(e)
solid/solid
function Button(props) {
return h('button',props)
}
function App() {
return [
h(Button,{onClick(e){console.log('Hi')}}, "Ok"),
h(Button,{onClick(){console.log('Hi')}}, "Fail")
]
}
I would expect their not to be a difference in behaviour
No response
No response
This will cover best practices for creating accessible UIs with Solid. Can include solid-aria
. More research required.
I wanted to contribute translations to the old docs but held off when I saw plans for a new docs site, since I wasn't sure about what would happen to the old docs.
However, in the new docs, I don't see any references to translation efforts/UI controls that allow for changing language.
Is the new docs still too early to consider i18n? And should people who want to contribute translations focus their efforts on the old site instead?
After solidjs/solid#1032 I'm still playing with reconcile
... let me report another issue I found.
An item unshift
ed is duplicated by reconcile
:
const [state, setState] = createStore<any>({
root: {
id: "dummy",
name: "",
entries: []
}
});
const root = {
id: "id0",
name: "ITEM 0",
entries: [{ id: "id1", name: "ITEM 1" }]
};
setState(reconcile({ root: root }, { key: null, merge: true }));
root.entries.unshift({ id: "id2", name: "ITEM 2 -- DUPLICATED!!!" });
setState(reconcile({ root: root }, { key: null, merge: true }));
console.log(state.root.entries[0].name); // ==> "ITEM 2 -- DUPLICATED!!!"
console.log(state.root.entries[1].name); // ==> "ITEM 2 -- DUPLICATED!!!"
(Note that the root
property at the top-level is to workaround solidjs/solid#1032.)
Although I don't know the exact definition of merge: true
, I think this is not an intended/expected behavior. As far as I confirmed, this duplication cannot be reproduced with one of the following modification:
push
but not unshift
reconcile
with merge: false
reconcile
with key: "id"
root
object instead of reusing the value altered by root.entries.unshift
I guess there are some (undocumented) limitation around reusing values when merge: true
... or essentially it's inappropriate for arrays modified with splice or unshift.
https://playground.solidjs.com/?hash=575260739&version=1.4.1
"name": "ITEM 2 -- DUPLICATED!!!"
appear twice.No response
No response
The way this reads could be more concise (See boxed text).
Text found here: Building UI With Components
As we learned above, Solid components return JSX. JSX is an HTML-like syntax used in Solid JavaScript code to represent part of the Document Object Model (DOM). In our HelloWorld.jsx example above, we returned the following JSX from our component:
Write concept pages that cover:
The Nested Routing demo:
https://docs.solidjs.com/start/core-concepts/routing-and-pages#nested-routing
Let's consider a UI to help us out. Hover or tap each button to see how each segment of the URL maps to three things: a component layout, a JavaScript bundle, and a piece of data.
Some issues:
The current iteration of the JSX section of the docs has a comparison with other frameworks. Among them is a comparison block to Vue the reads like the following:
Instead of JSX, Vue has its own "template language" that lives in a designated
spot in a.vue
file. This serves a similar role to JSX, but isn't directly
integrated into JavaScript. In Solid, you can write a JSX element anywhere you
could write a JavaScript expression, and there's no enforced separation
between template and data.
However, there's a bit of nuance here that I think is potentially misleading without further explanation:
.vue
files. Instead, you can declare multiple Vue files within the same file by utilizing objects and/or the defineComponent
API, either with the template
property.const Comp = {
template: `<p>Hello world!</p>
}
Should we modify the existing language in any way to reflect these, or are they more considered "edge-cases" that are outside of the scope of our documentation?
template
field in the @Component
decorator like so:@Component({
selector: 'my-app',
template: '<p>Hello, world!</p>'
})
class AppComponent {}
And utilizes a compiler to convert this template into instructions. Would similar language to Vue's work here, with that in mind? Would we need to change the language for just Angular? For both Angular and Vue?
Guidance is appreciated ๐
Migrate from the existing docs, after the concept pages have been written. The API and concept pages should be interlinked, and much of @edemaine's explanations in the API reference will end up in concept pages (especially in Diving Deeper sections).
While I understand the focus of JSX in our docs currently, one of the things that made Solid stand out to me initially (and helped distinguish it from compiler-based solutions like Svelte) was its ability to run its templating at runtime with the usage of @solid/html
.
Would it be worthwhile to include an aside in our What is JSX
section that indicates that JSX is not the only choice for Solid - simply the default pick?
After noticing one of our main pages ("Welcome") not having a <title>
usage in #64, I think it would be a good to add a home-grown ESlint (or similar) rule to enforce this for new pages we add.
I'm assigning myself, since I've had a fair bit of experience with both ESlint and AST-based plugin creation
While speaking with @Jutanium, we touched on the idea of having images (and/or animations) to represent concepts that work with a visual medium (such as index tracking for For
).
However, this raises the concern of consistency - it would be nice to have some common layouts and examples of what a chart/image would look like in docs usage.
Examples within the React ecosystem:
Some thoughts:
A how-to guide to creating and publishing a SolidJS library/package on NPM.
Currently, we're using file-based routing for our blog posts in order to define URL routing.
This leads to a problem where in order to find any given content, we have to navigate into:
src/routes/guides
Which is intermingled with source code and can be challenging to find for newcomer contributors that intend on solely contributing to our docs, and not our infrastructure codebase.
Per a discussion I had with @Jutanium, we would like to move to something of a similar model that I use for the Unicorn Utterances codebase where we have split root folders for these, like so:
src
- Where our infrastructure code livescontent
- Where our blog posts/documentation/etc livesThis means that in order to do this, we need to move away from file-based routing, and toward parameter-based routing.
I've started a WIP example branch here:
https://github.com/solidjs/solid-docs-next/tree/co-locate-guides
You'll notice that if you attempt to run the code in my branch, it will fail. This is because, as I understand it, the current codebase:
However, because our Vite plugin compiles MDX files to a function, this does not work. AFAIK, solid-start
has the same limitations as NextJS's getServerSideProps
in terms of required serialization going from the server to the client via routeData
In order to solve for this problem, I've previously (for UU, which uses NextJS):
rehype
instance in order to add some specific plugins and transformationsrehype
This leads to a problem where our initial hydration of the page leads to duplicate data between the HTML passed to the client and the HTML that our second rehype
instance runs into.
It's unclear what the best decision of overcoming this implementation detail would be. Advice/guidance would be greatly appreciated.
Once a decision is made on what to do next, I'm happy to work on the code to make this a reality.
A self-contained guide answering the question: "How do I set up Vite for Solid from scratch?"
Includes Typescript setup and explains how Vite plugins work.
This answers the question: "How do I style my Solid app"? It will compare different approaches and provide a practical way to choose a solution for your project.
Write concept pages that cover the following:
When you select any of the framework options (probably because the page content changes), you lose your current focused element (it goes back to the tabindex 0 element). This is very bad UX for keyboard-only and screen reader users. You would expect the change from the selected framework to just maintain your focus on the selected radio. This problem doesn't happen with the TypeScript/JavaScript radio group. Here's a gif that shows how I lost focus changing the framework but I don't lose it when I change the JavaScript/TypeScript radio:
I'm not sure why this is happening, so unfortunately I'm not going to submit a PR for this one.
Explaining Solid's API design philosophy. Points from here, but heavily rework to be beginner-friendly:
This will likely be in a special Concept page or a Foundation page.
Migrate from the old site.
Previous discussion with @Jutanium on tone within the Docs. It's not the responsibility of the Docs to provide hype.
Removing the exclamation mark on
src > routes > tutorials > getting-started-with-components.mdx
line: 184
Great first issue
We start with the existing guide. This is a perfect candidate for an interactive Stackblitz-based guide.
The Storybook API has changed quite a lot since Solid's Storybook docs were written in 2019. It would be really helpful (and I think go a loooong way toward helping drive adoption, long-term) if Solid could:
Storybook's become a pretty essential piece of the UI development pipeline, and at least for me, official support for it is a prerequisite for seriously considering any frontend frameworks. I miiiight be able to help with setting this up for Solid, although I haven't tried adding support for a new framework to Storybook before. ๐
Concept guides on Context, Stores, and how to use the two together for state management.
This would provide in-place definitions for technical jargon, including Solid-specific terms. This can also link to Concept pages, and could even let you browse all usages of the word.
The existing reactivity guide is a good starting point: https://www.solidjs.com/guides/reactivity
We also have a new Tracking concept. Need to determine how these fit together (or if one should include the other): https://docs.solidjs.com/reference/tracking
After some discussion, the following topics are too advanced for this introduction to reactivity:
A guide answering the question: "How do I write idiomatic Solid code"?
I'd like to structure this in a step-by-step / progressive manner, rather than dumping a list of rules on the reader.
When the user is instructed to change the name of the Function from App to Bookshelf this breaks the Rendered function. The name "App" is still referenced in the index.jsx.
This is then referenced by the index.html file. to generate the App.jsx file.
All this can be found on lines 280 - 293
I think in order for the user to build the app fully they should be instructed on a few steps before adjusting the Function name. At least to show the relationship of the files mentioned.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.