Help Me Understand Documentation Holes

I really would appreciate feedback here. It is so hard for me to see it since I've been so close to this for so long and I've developed apps in this manner for 10 years. I'm going to be the worst person to write the documentation since it is all so second nature for me. Yet, I am most likely going to be the person writing the documentation since I understand how everything works so well.
So can you please comment on anythings you found confusing about Solid as you've been trying it out, using it in your demo projects, integrating it with 3rd party libraries. And if you did find a solution can you comment on what you feel would have been the easiest way to describe it to you. Even if it takes me some time to compile all of this I think it would also highlight some early gotcha's for people trying the library.
I know I need to do a lot better here but this is a bit of a blindspot for me. Thank you.

I think having a formal API generated from the codebase would be very helpful; sometimes it's hard to find which methods are available, what are they called or what types of values are accepted (I'm thinking about all the possible way to call setState).
I found myself looping over the files in https://github.com/ryansolid/solid/tree/master/documentation until I found the answer
Given it's a typescript codebase, https://typedoc.org could be helpful, even if it's not the most flexible generator (it looks something like this on a project of mine: https://framp.me/frappe/docs)
My background is mainly React and derivates (from Classes to Fn/Hooks) + a fair amount of elm + very little vue.
My surprises:

createState works only with an object, I was expecting to createState('string'): I had to enter in the mentality of using a signal over state
state is a Proxy over signals: I keep thinking of state as a simple object while it's instead a Proxy (which led to my question here https://github.com/ryansolid/solid/issues/166)
createEffect doesn't support explicit dependency tracking: using createDependentEffect instead works fine - I wonder if there is a specific reason to have both functions though?
No hook rules: this is definitely positive and freeing, no solution needed

I probably would have described the system starting from reactivity and introducing the simpler primitive and then building up to state.
I'll try to come up with some tutorial / writing on this and get back to you.

I know there's an open issue about SSR & SSG, but a more detailed documentation about it and how to set it up would be really nice. I think that's going to spark a lot of interest, especially if you manage to get it close to Marko/Svelte rendering.

@framp this is great stuff. The state naming is an interesting thing in the post Hooks world. See I started calling that beforehand because I was trying to emulate React Class Components state object. But now people are used to useState. That's a good point. I'm not sure I'd call signals state because that is just as confusing being functions. But it brings up a good point.
createEffect being separate is mostly for code size. It is the most used reactive primitive and is used everywhere in the views. The number of times I've wanted createDependentEffect are fewer but they do exist.
Yes I need to document create solid better.. It is just a fork of Create React App. I just pointed at CRA docs because that all applies but it's worth talking about that. For instance adding module.css as the extension I think does CSS modules out of the box(https://create-react-app.dev/docs/adding-a-css-modules-stylesheet/). The problem is there is so much in CRA that I don't know how it works. Of course I should just make that a lot clearer.
Thank you so much for this feedback.
@amoutonbrady .... hah.. you got me. This is purposefully cryptic right now since I'm making breaking changes even in patch versions. I shouldn't be but I don't want to bump the minor version to infinity while I work on this. I know how to get Marko/Svelte performance but it comes at real cost given the scenarios I want to support. I almost have to start over and build up again to get there. Basically they render a static string with no reactivity on the server this makes advanced patterns very limited.

I can't really talk about what the experience of someone with no experience in other frontend frameworks would be, since I'm not that person, but as someone who has mostly only worked with React as well, coming to Solid when I see things that are named "Effect" or "State", I would really want to know either exactly how they differ to React effects and state, or if they are substantially different, it would be nice if they were named something else entirely.
I think the problem with the current explanation of Solid State in the README is that it isn't 100% clear exactly how effects or state work in Solid.
For example, React hooks execute every single render, or if you add state variables into the dependency array, only when those state variables get updated. In Solid's README if you read the provided example code one might be able to deduce that the effect only executes if state variables used inside are set through their setters, but it would be good if this was stated explicitly in the explanation. Also, it still leaves a few questions unanswered, like "so does the effect ever execute if state variables inside are not set?", and "if one uses a specific path inside the state object, does the effect only execute if that path is updated? Or just whenever the setter is called?". Whichever is the case, a more explicit explanation would be nice.
You also don't explain:

memos, which are mentioned as being the other kind of "computation", aside from effects
what you mean by "subscribers" in Each setState statement will notify subscribers synchronously with all changes applied.

The two linked introductory articles are a bit better, but explain by showing some amount of the implementation, which can be insightful, especially in this case where the underlying implementation isn't hugely complicated, but can also be confusing to some people. Generally speaking as well, while talking about implementation detail can be fine if it is explained clearly why they make things work they way they do, it introduces one more thing that a new user needs to understand, and is only useful if it helps them understand how to use the library, or helps them understand why the library is good/superior.
I also understand if the introduction on State is merely meant to motivate, not explain, but in that case I would expect a more thorough explanation on both State and Effect somewhere else in the official documentation (and not an article written on another site). And also, if the goal was to motivate, personally speaking, I don't see from the provided examples how the library is all that different to React, and if I was a beginner it wouldn't really occur to me why Reactivity is even that important in the first place. It's only through digging through other parts of documentation and the two articles that any of it clicks into place.
The Reactivity.md document starts by talking about Signals, but I hesitate to actually read about them, because 1. I'm not sure whether it's actually necessary to understand them, and 2. the actual explanation for what signals actually are seems to mostly be a very heavy two paragraph section titled "Accessors Reactive Scope" which should really have more code examples to demonstrate what you mean by things like "reactive scope" and "can be nested as many levels as desired". If signals are just implementation detail then I don't really want to read about them.

@louisch Thank you this cuts to the heart of it. I've had difficulty explaining the reactive update model without going into implementation. Any wordy explanation sounds like vague generalizations or like I'm selling magic. This always detracts from having a simple message.
I do see a couple commonalities here:

Use of terms used in React even if React doesn't own the term (Effect, Memo) is generally confusing. I did choose them intentionally for familiarity, especially State. At minimum need disclaimers like the Suspense side.
Unclear the role of State vs Signal. Emphasizing state initially undermines learning core concepts.
More detail on mechanism of reative rendering. And how it builds on top of reactivity basics.

@ryansolid I think you should this example of shared state between multiple components

const Right: Component = () => {
  console.log(state); // global state
  const div =
 as HTMLDivElement;
  let localvar = false;
  function update() {
   // This won't execute every time counter changes
    if (localvar) div.textContent = `${state.counter}`;
    localvar = !localvar;
  }

  createEffect(() => {
    if (state.display) { // value of display changes every 4 seconds
      update();
    }
  });
  return div;
};

@junaid1460 did you remove another example? I actually liked that one. Since it showed something that I took for granted. Computations re-track dependencies on every execution. If you ever hit branching logic that doesn't depend on a reactive stat the other branch will never evaluate and the branch itself won't since it isn't being tracked. I think the execution cycle of reactivity tracking could be better explained.
As for the CodeSandbox example has a lot going on so I'm unclear what precisely you are trying to demonstrate. Generally I recommend following React-like patterns even if it is unnecessary. I find that code organization easier to understand the basics like props and eventually context. Again perfect example of where I'm assuming React knowledge.
It is possible to hoist out signals and state, but you don't want to do so with effects and memos since they will never be released. For that reason I strongly suggest following the Context pattern. I have examples about how that works and docs. But maybe I need a more of.. writing your first app etc.. Or like after a writing your first Component, a next steps.
I'm thinking this mostly boils down to having good tutorials. The examples are ok, the docs definitely have holes, but as much of it is they go too deep in areas a beginner doesn't care to as of yet. I need the documentation to be complete but there should be a path for people who don't care for those details. I introduced state early to let people coming from React try easy stuff almost as a drop in.

Yeah, kinda changed it. with making two components almost similar except for one line. I was trying to explain how tracking works. May be you could include a simple example best practice doc
Also there's some other pattern like
passing JSX element directly in props might cause duplication
like for example
function Test({array, index}:{array: any[], index: number })  {
    return array[index]
}

function Root({index}: {index) {
    // Avoid this
    <Test array={[<MyBigComponent></MyBigComponent>, ]} index={index} />
}

function Test2({array, index}:{array: any[], index: number })  {
    return array[index]()
}

function Root({index}: {index) {
    // do this
    <Test2 array={[() => <MyBigComponent></MyBigComponent>,() =>  ]} index={index} />
}

Is the confusion that all dynamic props are lazily evaluated? And:
<MyBigComponent />
// roughly equals
MyBigComponent()

Because I don't see an issue in the first case if that is what you are going for. Can you explain why don't do this? I also notice you use a lot of destructuring which shouldn't be a problem here but could lead to missing reactive triggering. I'm thinking that something even more fundamental is missing in the docs and following that assumption we've gotten out here somewhere.
Maybe there is a bug here that I'm missing as I expect the first scenario to be fine. Maybe my heuristic for dynamic wrapping is incorrect in these component cases? I feel like I'm missing part of what is trying be achieved here. Using onCleanup should regardless of how inefficient the rendering is (redoing work etc) should still release any side effects.

I have migrated a project from react to solid, I noticed this with a tab component, during change, updates were triggered in two createEffects, out of which one is visible and another was just invoked by this <MyBigComponent />.

Haven't tried solid yet, but read a few articles by @ryansolid & documentation pages in this repo. Solid looks like a very promising project and I really want to see it gaining more traction among developers.
With that, I'd strongly recommend the project to have its official website with documentation before/with going v1.0. If you're already planning on that, please disregard the rest of this comment. 😅
As silly as it sounds, presentation matters. A lot. A nice, clean website to go with the documentation will attract new users and help to retain current users. This is especially true for those who are not as knowledgeable/interested in the underlying technologies but still curious about what the next big thing might be or simply looking for some great off-the-shelf tools to build applications with.
A link to the project website also looks much better than to its GitHub repo when spreading the word. Unfortunately, https://github.com/ryansolid/solid just doesn't give off an impression that this is more than an experiment.
Nothing too crazy--something as simple as https://recoiljs.org/ should suffice in my opinion. You already have all the materials.
Best of luck to you!

@bobaekang I agree completely. It is already in the works. I hope to get it in place soon. It is probably the biggest outstanding piece for 1.0. I wouldn't mind stabilizing on SSR a bit more and a bit of cleanup around Resource APIs for Suspense. I think starter templates could be improved too.
I appreciate the feedback.

@bobaekang I agree completely. It is already in the works. I hope to get it in place soon. It is probably the biggest outstanding piece for 1.0. I wouldn't mind stabilizing on SSR a bit more and a bit of cleanup around Resource APIs for Suspense. I think starter templates could be improved too.
I appreciate the feedback.

@ryansolid could you please drop a link to repo here.

Right now it's a private repo. I will likely change when I have something to show.

Can you elaborate on reconcile in documentation/state.md?
Specifically, how does using reconcile differ from just plain setState? What concrete use cases are there for reconcile? User login? Can you provide some examples of the resulting state after setState with and without reconcile?
Does store.get('users') in the example return an array of objects with at least an _id field which is to be used as the key for diffing?

Just started looking at Solid (having found it via interest in Svelte). I'm most familiar these days with React (and Redux), but have used a bunch of approaches/tools over the years (including good ol' VanillaJS).
Solid looks very interesting, especially as I've hit some performance bumps recently with React in a side project. I know I can work around them, but I keep having this feeling that browers and JS are incredibly powerful these days and we are actually getting in our own way with a lot of our 'solutions'. So Solid's focus on being fast resonates a lot!
Regarding docs, some general points that would help folks like me jump in are:

A tutorial. Side note that I think Svelte really did a good job here.
A clear opinion on recommended approaches to common problems (whilst leaving the door open to other approaches).

Right now there is a ton of information that I've read through about Solid that's got me excited about it. But I also notice that I haven't yet tried playing with it because I dread having to make a bunch of decisions (even which 'starter' to use). Reducing those decisions by providing a strong opinion would help a lot here.
I looked over the realworld and hackernews source. I think it would be amazing to document the decisions made (and accompanying rationale) when implementing those - could be the basis of the tutorial? Are they recommended patterns for Solid usage?
By the way, the general explanation of why (along with the what and how) in the current docs/articles is very useful and something often overlooked in docs. Distilling these down into a summary of the tradeoffs made could be helpful to folks evaluating potential fit for their projects.
Lastly, a tie-in with an existing service can be a boon to adoption and visibility. I saw #100 and think that getting an article on their learning section could be a good idea. They are also a good example of real-world articles that get you into their product by showing how it works with other common products (like Auth0).

Really like the idea of having a tutorial/tour page of Solid's features.

https://svelte.dev/tutorial/
https://tour.golang.org/

@martinpengellyphillips Yeah I did try to streamline at least getting started. The challenge is everyone has their own opinion.  I have Create Solid App. And truthfully the fact that I wouldn't use my own starter probably says something. In general, I've found the process on tooling has generally been I suggest something and everyone points out how they have a different use case. This is a problem with the JS ecosystem in general. There is no one size fits all here. For larger projects people have more patience for bloat. I find most early adopters would rather start pretty minimalist so something like Create Solid is way overkill. But it also isn't there for them. I pictured most people would just start there as documented.
I tried to write an article for how to build TodoMVC but I feel it fell short. The real challenge is answering "why" without getting into very specific details of the reactive system. From my perspective most libraries gloss over this a bit. They just go, this is how you do blank which I think is probably sensible from an intro perspective if why makes the explanation 4 times longer.
Personally I think the single best way to try SolidJS without any commitment is modifying one of the over a dozen examples from CodeSandbox I link off the readme. That's how I learn. That's the poor man's version of tutorials. Which really just brings us back to the tutorial/guides which keep coming back in these comments. I'd love to be able to do something like that. But it starts with getting a REPL setup. Something nice that shows code running, as well as compilation output. That is pretty much the requirement to make those tutorials effective. I've had Solid compile in the browser before using Babel Standalone but this needs to be much better. With that I think the rest of this comes. I'm not sure if there are existing editor tools that can be used? I know Svelte built theirs from scratch.
I could make an issue around creating a REPL. It's just one of many things that will take some doing. As much as I'd like to do stuff like this to promote the library. I've resigned myself to prioritize things that only I can do at this point and things that others could help with like say Routing, creating a Website, or creating a REPL I'm going to leave out there for now. If anyone wants to help would be super appreciative. Otherwise I will get there eventually.

@ryansolid I hear ya!

I could make an issue around creating a REPL. It's just one of many things that will take some doing.

I personally don't think you need a REPL tutorial (it's a nice to have).
What I was thinking more about was some clearer sense of "Ryan's sitting down to start a new project with Solid - what do they do?". And I think that, as the creator, you totally get to give your opinion without worrying about satisfying everyone elses 😄
And maybe you don't use starter templates and just spin things up from scratch. If so, I'd say that in the intro/tutorial because it helps establish the culture ('lean and mean', 'back to basics', 'understand your tools', ...) and it also avoids folks spinning the wheels too much on 'am I doing this as intended?'

And truthfully the fact that I wouldn't use my own starter probably says something.

I totally clocked that and it was a stumbling block for me getting started because I wanted to know why doesn't Ryan use this? Can I do what they do instead?.

Personally I think the single best way to try SolidJS without any commitment is modifying one of the over a dozen examples from CodeSandbox I link off the readme.

I think that's a good way to try bits of Solid, but for me it's not a hook to use Solid. I need to build something with it and see how the pieces fit together. And that means I need low friction on getting started on my own project. As an aside, CodeSandbox is typically slow so not a great compliment to a project that focuses so much on performance 😉. Also, some of the examples (e.g. form) seem slightly broken and there is a lot to go through up front.
BUT, to stay true to my first point, if you think lots of examples via sandboxes is the way to go, then just stating that clearly will help folks get in the groove.
In the meantime, if I'll take a punt at converting one of my existing apps to Solid and let you know how it goes.

I'm not sure if I've missed this, but one topic that may be worth covering is how to generally approach the integration of 3rd party vanillaJS libraries with Solid (e.g. libraries for animations, drag-and-drop, etc.).
This is a topic that has been in the back of my mind while thinking about (and very much wanting) to use solid for an upcoming personal project. I don't know if I've overlooked or just failed to understand something, but there could be other dumdums like me that are also unclear as to what to consider and how to approach trying to use existing vanillaJS libraries with Solid.

That's fair. I think I assume too much React knowledge and don't provide any guides for this as it is a bit outside of what the library does. In one sense it's really simple, which is why it gets missed I think since:
// this is an HTMLDivElement
const div =

In that it is pretty easy to do Vanilla JS since you just get a reference to the element and do what you would with it. You can also get refs via the ref bindings https://github.com/ryansolid/solid/blob/master/documentation/rendering.md#refs.
If you need to cleanup when your component is destroyed you can add an onCleanup call to clean up any side effects.
Albeit I don't have great examples. This thread might be of interest: https://github.com/ryansolid/solid/issues/39 I'd be interested in more concrete examples as a source for guides.

As kind of the culmination of the long chain of questions I had in #215, I think this line:
While you don't see them, everytime you write an expression in the JSX, the compiler is wrapping it in a function and passing it to a createEffect call.

in the Reactivity docs could use a bit more elaboration. Reactivity in Effect and Memo are very clear, but it's a lot more opaque when it comes to JSX, I think. I originally interpreted this as meaning of "an expression in [the] JSX" as "a JSX expression" as in "All JSX is compiled to a createEffect call", which lead to the assumption that anything inside the body of a Component function would therefore be reactive, but from the conversation we had and the article you linked, I understand that's not the case. I'm assuming now that "an expression in JSX" is what the curly brace interpolation thing is called, and I guess I just never picked up on that. So, does this mean that any function that's ultimately invoked within JSX bracket whatevers is reactive? Does this apply universally, like in props and such? I think it would be useful for people who are prone to making way too many assumptions, such as myself, to explicitly lay out where the boundaries of reactivity are.

@Myrdden Yeah it's all good. It just means they can be better. I made a lot of changes thanks to @louisch comments. But you bring up such an obvious thing yet not obvious to me since I am in it all the time. Those curly brace things are called JSX Expressions in the spec and the AST parsed. I actually named the underly DOM Expressions after this concept but it is in no way obvious since in JSX from a JavaScript perspective everything is an expression.
To answer your first question yes. Component execution bodies themselves are untracked, but every expression which can be reactive inside a JSX Expression is reactive. The compiler uses syntax analysis to determine this. Things that call functions or access members (like array or object property access) are treated like they are reactive. Function declarations, literal values, and simple identifiers that can never be tracked are not (it's a little bit more complicated than that but that's the message).
Second question. Components instead of wrapping things in createEffect only wrap these in functions and mark the property as dynamic. It creates a getter on the props object at Component creation time. The reason you want to do that is to universalize the API. You could pass the getSignal which as a function could be accessed reactively with no extra wrappers, but it would be the child's job to decide if they had a signal or a simple primitive value. That is unacceptable from my perspective. So you are better to resolve it in the binding like your example and then props.someProp will only run getSignal() when you access the property, and if you call it at a non-reactive call site like with a string value props.someProp will still hold the right value. So it's universal. But this clever little trick prevents creating excessive intermediate reactive primitives, unifies signal and POJO interfaces, and removes the need for an isSignal operator or any sort of special consideration for the Child Component based on what is input.

Neat, that totally cleared it up for me. My takeaway is basically that the assumption can be made that anything inside of Effect, Memo, or a JSX Expression is reactive, but I think that did a good job explaining why.
One more question, how exactly does destructuring work? Is it just "never use it with reactive things"? I understand that ({someProp}) => ... will break reactivity, but will (props) => const {someProp} = props; ... do so as well?

Honestly I think this is the by far the biggest one. It's all variations on this topic of reactive context. All reactive libraries fundamentally work the same but since I don't do this at a Component scope it causes a lot of confusion. Unfortunately it is the thing that makes this approach interesting from performance standpoint. Why it is able to do the 1:1 updates that no other library even Reactive ones like Svelte can do.
It's much easier to just say never destructure. But the truth is for something to be reactively tracked we need to call a function. We can hide that function behind a getter or a proxy but we need to call a function while the reactive context is executing. So nothing is wrong with destructring as long as you are in the right place.  Destructuring is accessing properties on an object and assigning them to a value. A value can not be reactive. So it matters where you access that property, so a destructure tracks like any other reactive access. But if you do it at the top of your file no one is listening.
I looked at Vue 3 docs for suggestions of how to explain this as they have the same problem in their setup function.  But it's verbose and expensive. I guess I could write simple function wrappers with explicit keys but it stops looking like destructuring. It becomes sort of self-defeating when the goal is to keep things terse. I could do it with a proxy maybe and keep the syntax tight. It wouldn't work in a rest parameter.
Like:
const {someProp} = toSignals(props);

// now someProp is a function and reactive when called.
someProp()

The request has come up a couple times now. Any thoughts on something like that? A bit more ergonomic perhaps than p.someProp?
We do have some other helpers like splitProps that I use for common cases where you want to spread portions of the props to different children and want to retain reactivity.

Personally I'm happy with "never destructure reactive props or else they'll break". I usually tend to use use p.someProp anyways, I just wanted to be clear on the behaviour. That said, I suppose a helper wouldn't hurt if one is really committed to destructuring.

Hello, another question... Maybe this goes in it's own ticket? Not sure.
I recall you saying somewhere, I don't remember where, that <Component/> is the same as Component(). If I assume this is universally true, will I run in to any issues? For instance, if I have:
const Component = () =>
hello
;

const App = () =>
<Component/>
;
// versus
const App = () =>
{Component()}
;
// or even something like
const App = () => wrapDiv(Component());

will these all function exactly the same? Or is there some other logic to <Component/>?

Yeah I might even remove createComponent in the future out of the JSX output. Props are the difference. Effectively this is what is happening if I were to do it at compile time.
// consider:
<Component prop1="static" prop2={state.dynamic} />

// becomes:
sample(() => Component({
  prop1: "static",
  get prop2() { return state.dynamic }
}))

Does that makes sense?

Yeah, that functionality makes sense. The question was more, if I do

{Component({prop1: static, prop2: () => state.dynamic})}

or something similar, the end result is exactly the same, yes?

Props expect to work on simple property access. so prop2 should be a getter so you can do props.prop2 not props.prop2(). This universalizes it. Secondly they should be in sample to avoid the Component render body being tracked. So what I wrote above would be the near equivalent. Technically since it returns a function and looks dynamic it will create an effect that is immediately sampled. So it will function the same but add a few bytes of extra memory.

Hello again, noticed mutable functionality has been split off recently. Can produce be used with pathing? I.E. is:
setState('here', 'is', 'an', 'object', produce(obj => someMutableChanges);

valid syntax or does produce have to be consumed by setState directly?

Oh yeah it can be on the path, any of the state modifiers work the same way. I can update examples. Thanks.

Also, would you say that using produce is the best way to delete keys? Or is there some way to null out keys or set them to undefined using setState? Will that break things?

You should just set them to undefined. You are right I don't mention that anywhere. https://github.com/ryansolid/solid/blob/master/packages/solid/src/reactive/state.ts#L106
If you need to remove items from an array provide a new array without it.

@ryansolid can I use Solid with another state manager? For instance, this state manager has state.subscribe(changes => …) API.
Real use case: can I use GraphQL library or my Logux with Solid without rewriting core to Solid State.

Yes. I mention this briefly but I have a reconcile function that will data diff immutable data structures and apply fine grained updates. You still use Solids state in your views but a minimal wrapper should take the immutable updates and convert them to more granular ones.

@ryansolid how i should extend props?
for example, with React i do this:
const Component = ({ className, ...rest }) =>

//in parent jsx

<Component className={cx(theme.item, { [theme.active]: active )} onClick={handleComponentClick} />

How i can do this with solid-js?
I use signals and i loose theme.component class from Component when signal value changes
const Component = (props) =>

//in parent jsx

<Component className={cx(theme.item, { [theme.active]: !!activeSignal() )} onClick={handleComponentClick} />

*cx - is clsx package

@oleggrishechkin I think you are looking for the splitProps helper: https://github.com/ryansolid/solid/blob/master/documentation/api.md#splitpropsprops-keyarrays-splitprops. You are correct identifying this needs special consideration. Hmm.. now that you mention it I only put examples in the release notes.

@ryansolid Thanks you for quick answer! It works as i expect for first look.
So, I think you should add examples for API page with simple usage like you comment above

@ryansolid How can i combine refs?
I provide ref to Component this way:
let ref;

<Component ref={ref} />

// I also want provide `Component` ref to another component and set `Component` `scrollTop`  directly from `OtherComponent`

<OtherComponent componentRef={ref} />

In Component I want set scrollTop (for example)
const Component = (props) => {
    let ref;
    setTImeout(() => {
        ref.scrollTop = 100
    });

    return

}

But, how can i use both - ref from props and local ref?

Thanks for editting your issue I was so confused at first about what was going on. Part of what you are facing is part of my motivation behind #225 .
That being said if you have 2 components one which gets a ref and one that is passed a ref like:
let ref;
// get the ref
<Component ref={ref} />

// sends the ref
<OtherComponent componentRef={ref} />

In the first one that gets the ref you want to be able to set scrolltop as well? This might be the easiest. If defined components should get a props.ref that is function. I tried to explain this in the docs but not sure it's clear. https://github.com/ryansolid/solid/blob/master/documentation/rendering.md#refs
const Component = (props) => {
    let ref;
    setTImeout(() => {
        ref.scrollTop = 100
    });

    return
 ref = el && props.ref && props.ref(el)} />
}

As for the setTimeout thing I'm not sure how 3 setTimeouts would do anything special. It is possible without setTimeout that the ref hasn't been connected to the DOM yet, but by the time the synchronous execution is done it should be connected. So I'm not quite sure how that would make any sort of difference. Is it some arbitrary time.. Like if you setTimeout 10ms does it also work?

@ryansolid Thanks for your anwser,
I tried props.ref(el) before write my previous comment (I read the docs, honestly) but it causing infinite loop (may be it's a bug), I understood it so that props.ref(el) set let ref from parent and Component updated, because props.ref changed... and set let ref again...
I try you solution
About timeouts:
10ms timeout not working, 100ms works fine or 3 setTImeouts calls works, 2 not works... I tried set scrollTop in afterEffects, and in ref=((el) => { el.scrollTop = 100 }) - not working without 3 setTimeouts too

@ryansolid After reviewing the docs, I wasn't certain the best/correct way to explicitly set a dependency for createEffect.
So I looked through issues and I found an issue where you discussed this. https://github.com/ryansolid/solid/issues/27
I tried both methods you shared, but only one of them works.
This works:
  createEffect(() => {
    order.type;
    // Do this when order.type changes
  });

But this doesn't:
createEffect(() => {
    // Do this when order.type changes
  }, [() => order.type]);

I actually prefer the second way as it's more similar to React/Vue Composition API, but in my testing only the first example works.

Oh weird I must have copied and pasted from the React example. I am trying to remember if I ever supported deps that way with createEffect. I did have a special primitive for it at one point(createDependentEffect) but it was only for one type of computation so I ended up removing it. I have createMemo, createComputed, and createEffect. The second argument in Solid's computations are the initial value which let's you perform reducing operations. Technically the deps are figured out at runtime so it adds extra code for everyone not wanting to be explicit.
I wasn't aware Vue did that. I haven't seen any examples where they use explicit dependencies. The advantage of explicit dependencies is to not track random things you don't expect. I use untrack for that. I'm not sure it makes sense to add this on all computation types etc as a 3rd argument. Or just rely on the untrack. Given my usage definitely the latter but years ago I had a different opinion.

In Vue it can be accomplished with the following.
watch(
  () => state.count,
  (count, prevCount) => {
    /* ... */
  }
)

https://v3.vuejs.org/guide/reactivity-computed-watchers.html#watch

Thanks. Yes I see. Right now my signature for these are:
// derive a value
function createMemo<T>(fn: (prev?: T) => T, initialValue, comparator): () => T

// synchronize before render
function createComputed<T>(fn: (prev?: T) => T, initialValue): void

// after render
function createEffect<T>(fn: (prev?: T) => T, initialValue): void

I'm not sure if I can override these reasonably. I mean it's easy to create this watch behavior it's just extra. I could make it an modifier I suppose:
function on(deps, fn) {
  const isArray = Array.isArray(deps);
  return (prev) => {
    let value;
    if (isArray) {
      value = [];
      for (let i = 0; i < deps.length; i++) value.push(deps[i]());
    } else value = deps();
    return untrack(() => fn(value, prev));
  }
}

And then we could use it like:
createEffect(on(
  () => state.count,
  (count, prevCount) => {
    /* ... */
  }
);

Seems reasonable to me. I have a whole library of similar modifiers in solid-rx and it would work with any of the build in computation types. It also doesn't push extra code on people who don't use the feature (we really aggressively tree shake around here). We could even change up the signature a bit to use rest parameters so you wouldn't need to pass an array ever and the last function would be the reaction. We could also do the same with the arguments making the last the previous value.
Does that seem interesting or useful to anyone?

My suggestions for the docs:

I would like to see a documentation website that I can search through. Using markdown files, there are many documentation generators that you can use right away without doing much.
The API page of the documentation needs to have a basic example for each.
Because there are no examples, on the API page, I have to use the tutorials, in which the information is kind of spread over different documents. For example, I had to go through a couple of links, until I found how to use onMount (found it inside the components page).
I wish there was a solid-zoo repository that we could share the solid-js components and examples. Something like a scrapbook of different components. The website can host them in the main repository or point to other repositories.

@aminya Thank you. A lot of good suggestions. We are working on the website/docs site. But i especially appreciate the detailed suggestions regarding giving examples with API, and component converting guide.
We've recently been talking about how to better showcase the community projects. There are a couple ideas floating around but are pretty ambitious. Initially it might be nice to move links from the project resources docs to a dedicated repo.

Many of these have been mentioned above, but I'll repeat again as a way of showing interest. Also, I'm just getting started with the library, so they could be entirely wrong:

A docs site using one of the book-style templates would be helpful for jumping between sections
Please don't assume knowledge of React or other libraries. When learning Solid I felt like I needed to first read about a topic in React to have the mental context for interpreting this library. (I have much more experience with Angular and rxjs)
Subscriptions could be explained better. When are reactive subscriptions made and when are they unsubscribed? It all seems implicit in the signals, states and effects, but a diagram explaining all this would be helpful. Similarly, the relationship between signals and state isn't clear. I keep wanting to relate them to rxjs types (observables, subscribers, etc.). I think the difference is that state allows automatic subscription to nested properties, while signals don't, but it would be good to really break down how it all works.
Add types to the examples. It would be helpful if the examples were in Typescript and annotated with their type definitions. Understanding the types is key to understanding the library and showing them will save the time of hunting through .d.ts files
There are a lot of destructuring assignments in the examples. They definitely help with e.g. createState(), but getting in the habit of using them naturally leads to destructuring from props, which breaks reactivity. Maybe this will be made clear by showing the types (State vs T)?
I find refs confusing. I'm not sure what else to say, but the same word "ref" seems to take on different meanings depending on where it's used. This seems to be a React thing, so maybe I need to read more about it there. A diagram or type annotations might be helpful.

Many of these have been mentioned above, but I'll repeat again as a way of showing interest. Also, I'm just getting started with the library, so they could be entirely wrong:

A docs site using one of the book-style templates would be helpful for jumping between sections
Please don't assume knowledge of React or other libraries. When learning Solid I felt like I needed to first read about a topic in React to have the mental context for interpreting this library. (I have much more experience with Angular and rxjs)
Subscriptions could be explained better. When are reactive subscriptions made and when are they unsubscribed? It all seems implicit in the signals, states and effects, but a diagram explaining all this would be helpful. Similarly, the relationship between signals and state isn't clear. I keep wanting to relate them to rxjs types (observables, subscribers, etc.). I think the difference is that state allows automatic subscription to nested properties, while signals don't, but it would be good to really break down how it all works.
Add types to the examples. It would be helpful if the examples were in Typescript and annotated with their type definitions. Understanding the types is key to understanding the library and showing them will save the time of hunting through .d.ts files
There are a lot of destructuring assignments in the examples. They definitely help with e.g. createState(), but getting in the habit of using them naturally leads to destructuring from props, which breaks reactivity. Maybe this will be made clear by showing the types (State vs T)?
I find refs confusing. I'm not sure what else to say, but the same word "ref" seems to take on different meanings depending on where it's used. This seems to be a React thing, so maybe I need to read more about it there. A diagram or type annotations might be helpful.

This is really good feedback @thatcort. @ryansolid we're in a place with the website to apply these details and requests. The infrastructure is generally in place, however we need to dedicate time to re-structuring/sprucing up the markdown files.
Does anyone have suggestions about how the sections of the documentation should be laid out? It might be a good first step to deciding what needs to be written or re-organised.

This is really good feedback @thatcort. @ryansolid we're in a place with the website to apply these details and requests. The infrastructure is generally in place, however we need to dedicate time to re-structuring/sprucing up the markdown files.
Does anyone have suggestions about how the sections of the documentation should be laid out? It might be a good first step to deciding what needs to be written or re-organised.

Thank you @thatcort. As you mentioned a few of these have been brought up before. I've made some attempts to tone down the React-ness (pull it out to special notes) but they basically invented the jargon we use to describe these things and I shouldn't assume people know what that is. Sometimes I don't even realize it isn't a known term outside of React. Like refs and props are fairly universal (not sure about Angular, as it's one of the few frameworks I've never really gotten into), but we can try to do better to not assume. A challenge there of course is structure and organization since it's possible I explain refs in the refs section but then use it casually throughout.
I'm most interested by this though:

There are a lot of destructuring assignments in the examples. They definitely help with e.g. createState(), but getting in the habit of using them naturally leads to destructuring from props, which breaks reactivity. Maybe this will be made clear by showing the types (State vs T)?

It's valid point of confusion and yet intentional. Which means I'm still inadequately explaining it. Basically the reason there are spreads in those setters is that is not only a performant but very easy visual way of cloning arrays which we want to do in those scenarios. Destructuring is perfectly trackable, but not if you don't do it under something that tracks. So it isn't so much that you can't destructure props. You just can't do it at the top of your component. Of course that is a very confusing message, but until now I never equated the merging of fields in this category.  Better explanation of how Components play into the reactive system would help I think. But I'm not sure what else.
Other thought and I don't know where this sits. I've mostly avoided TS in examples because I didn't want to alienate primarily JS users. I know before I got into TS I thought it looked like a mess that made things look overly complicated. We probably should offer examples in both on the site, but I just wanted to point out while TS in examples can bring clarity it can also be a hurdle for adoption. I like it when say doing API docs to show arguments but it's a whole other thing in the "counter" example.. although I have moved more stuff in CodeSandbox to TS as of late. It's just something I'm thinking about.

Thank you @thatcort. As you mentioned a few of these have been brought up before. I've made some attempts to tone down the React-ness (pull it out to special notes) but they basically invented the jargon we use to describe these things and I shouldn't assume people know what that is. Sometimes I don't even realize it isn't a known term outside of React. Like refs and props are fairly universal (not sure about Angular, as it's one of the few frameworks I've never really gotten into), but we can try to do better to not assume. A challenge there of course is structure and organization since it's possible I explain refs in the refs section but then use it casually throughout.
I'm most interested by this though:

There are a lot of destructuring assignments in the examples. They definitely help with e.g. createState(), but getting in the habit of using them naturally leads to destructuring from props, which breaks reactivity. Maybe this will be made clear by showing the types (State vs T)?

It's valid point of confusion and yet intentional. Which means I'm still inadequately explaining it. Basically the reason there are spreads in those setters is that is not only a performant but very easy visual way of cloning arrays which we want to do in those scenarios. Destructuring is perfectly trackable, but not if you don't do it under something that tracks. So it isn't so much that you can't destructure props. You just can't do it at the top of your component. Of course that is a very confusing message, but until now I never equated the merging of fields in this category.  Better explanation of how Components play into the reactive system would help I think. But I'm not sure what else.
Other thought and I don't know where this sits. I've mostly avoided TS in examples because I didn't want to alienate primarily JS users. I know before I got into TS I thought it looked like a mess that made things look overly complicated. We probably should offer examples in both on the site, but I just wanted to point out while TS in examples can bring clarity it can also be a hurdle for adoption. I like it when say doing API docs to show arguments but it's a whole other thing in the "counter" example.. although I have moved more stuff in CodeSandbox to TS as of late. It's just something I'm thinking about.

Maybe this should be another issue, but I think it would be very useful to have the documentation of /documentation/api.md as jsdoc comments in the source, that file then could be autogenerated to avoid having to keep them in sync.

@vemoo, that seems reasonable. I do some funny stuff with multiple versions of the same functionality for client and server but the client docs probably would be sufficient for most things.

i copy pasted the "no Compliation" example into codepen and nothing happened. I dont really understand skypack so its hard for me to debug.

@simpleAdam Thanks for pointing this out. A recent change to managing our package exports broke that. It should work fine now.

In the reactivity section, "reactive scopes" are not well defined. It says signals "are trackable when executed under a reactive scope," but where do those scopes begin and end? I think the key sentences are "Dependencies are automatically tracked when you access your reactive values in your Effects and JSX View code." at the top and "The way Solid works is that each nested computation is owned by it's parent reactive scope." in the Cleanup section. All this would be much easier to understand if it were explicitly described in one place. A diagram putting it all together would be helpful too.

Just a thought but it'd be nice to know if you, the author, work on this full time or not. You see people might have their needs, demands, etc. that might turn out disrespectful since they want something and want it quick while not realising that you do this in your free time for free (if I'm correct, but once again I don't/cannot know since I haven't found this info anywhere). Overall the community around Solid is very nice but I guess it might be sometimes overwhelming for you.

@the-yamiteru That's true. This hasn't really been clear and I haven't felt the need to put it out there. I wonder if there are any repos with similar messages done tastefully that you've seen.
But yes this was my personal project to start although we now have more people working on Solid. I spend a lot of time on Solid, probably a little shy of 35 hours a week, but it isn't my day job. So I work as I see fit, which is pretty much every day. That being said I don't see much problem doing things as I get to them. Most OS projects don't have instant feedback anyway.

Biggest hole for me, which is discussed a little bit here, is how are dependencies determined?  For example, how does createEffect "know"  that the doubleCount function contains reactive data. Is it using custom/objects classes, is it using parsing + name checking, does that mean eval would break it? It's kinda just magic in the sense that the limitations of automatic dependency detection are not obvious.

I think this (how dependencies are tracked) was a major stumbling block for me as well, and has probably led to more than one bug in my code. This article was key for me to figure it out.
The short of it (assuming the implementation in solid is the same as the above article), is that whenever an effect (or any other reactive context, I think) runs, it sets a global context indicating the current running effect. Then, whenever a signal (or state object) is read, the signal registers that it was read by the current effect, and keeps a reference to it, calling it when the signal next changes. This is why reading a signal is a function call, and why state objects are actually getters.
There are a couple missing pieces here still, 1 if a signal triggers an effect, and is not read on the triggered effect, then that effect is unregistered, and no longer called when that signal changes (unless/until it is read in that effect again). Also, the effect always runs once without a trigger, and whatever reactive values are read in that runs will be used to trigger it next (as per the above).
The critical bit here (that has caused me some bugs) is that any reading of a reactive value, whether in the createEffect function or called by it, will trigger the effect when that value changes.

Yes I usually point people to that article, although I usually prefer this one first: https://dev.to/ryansolid/a-hands-on-introduction-to-fine-grained-reactivity-3ndf. More from a concepts level rather than implementation.
Those are the simplest explanations I have to date. The problem I've found when I've tried to summarize it by implementation is no one gets what I'm talking about. I think maybe the first non-obvious point since we get compared to Svelte is the reactive system is completely runtime. The mechanism is based on execution scope so biggest limitation is everything tracking must happen synchronously. It doesn't follow into async resolutions or closures of a setTimeout etc.

@jeff-hykin Just looking and Vue updated their docs some.. i think this might be what we need: https://v3.vuejs.org/guide/reactivity.html#what-is-reactivity
Does this make sense to you?

That definitely presents my exact question, although I don't think they need to get into proxy objects though. So I'll give a go at summarizing it for Solid JS.
(Correct me if this is wrong)
Any reactive function like doubleCount, needs to be executed at least once for the function to figure out what values (e.g. getCount ) it depends on. And this presents a few quirks:

If (because of an if statement or something) reactive values (getCount) are not called inside the function, then the function (doubleCount) won't know that it depends on the value (getCount)
Member values (e.g. thing.member) can be tracked, because behind the scenes they're using proxy objects or getters. This is how props and state work. This is why let member = thing.member breaks stuff.
To use primitives (that aren't member values) they need to be wrapped in a function, e.g. getCount instead of count. This is so that when doubleCount is executed, the getCount function can say "hey doubleCount; you're depending the count value"

Does this mean, if we want explicit dependencies, that we could just evaluate them at the top? Ex:
let doubleCountSometimes => {
    getCount(); // explicit dependency
    if (condition) {
         return getCount() *2;
    }
}

(If so I think that's a pretty important thing to mention in the documentation, and I'm happy to help add that)
If this understanding is correct, I guess this also means that async reactive functions would probably break createEffect since it wouldn't  be able to keep track of what was executing.

Also thanks for linking that section. In the absence of a good no-virtual-dom framework, Vue has been my go-to. After a year or so I've always avoided computed properties because of not understanding why they sometimes fail to update, and think that documentation you linked finally explains why.
Hopefully Solid JS documentation can prevent that level of frustration with more transparency.
Although JavaScript limitations makes the reactivity problem nearly impossible to solve, I think there needs to be a fail-safe approach instead of a fail-dangerous one. It is just too easy to forget, or for someone unfamiliar with solid, to use count instead of getCount, or accidentally use destructuring. I'll be working on a "strict" reactivity version. I think a modified JSX syntax would be best, but I'm not familiar enough with babel to handle that. I'll probably have to settle for templated strings. And if that doesn't pan out, I'll probably just go with purely explicit dependencies instead of a flawed automatic system. Vue using class-like objects does prevent a lot of problems, since it ensures  this was always necessary to access state/prop data. But obviously it is still fail-dangerous as I discovered with computed properties.

@jeff-hykin Yeah it's super tricky with JavaScript. It goes beyond the templating since you can't intercept just a value read. Which either sticks you on Solid/Vue path or Svelte (which is locked to the template). There is research being done to get around that but it is complicated. Generally speaking I think being explicit as much reasonably possible is probably the solution. One thing that I push with Solid is to always call the function on the signal and not just treat it like count since the second someone goes to format it change it then they need to add that. I used to have this issue always with Knockout and Vue is more of the same. I'd make using just count as you put it break everywhere if I could (it does on attributes) but for inserts it's also the mechanism for dynamic inserts so technically they allow functions. The problem with being explicit on dependencies is in the templates themselves. Unless you are taking a course grain approach no clean syntax to set deps per binding. I had these sort of issues with doing RxJS based templating. In the end I went back to automatic since it keeps things clean. Compiler analysis does auto wrapping of potentially dynamic values so you can just use it pretty naturally in the JSX.
Solid early days used a syntax to denote reactive values. It took me a while to find something that wouldn't break TypeScript but unfortunately Prettier killed it pretty badly. I used inner params {( state.value )} to denote reactivity. In some ways I miss the power of that system since it was so explicit but people still kept messing it up. Honestly just allowing { state.value } just makes more sense .. otherwise you end up introducing extra function syntax like {$(state.value)} etc.. It's a bit of a rabbit hole where this can go. Now that TypeScript supports namespaces you might be able to use that like $:class={}. They only added namespace support in February of this year which has been a real constraint. Of course you'd still need difference syntax to denote react/static children perhaps.
I'm hoping too documentation can help. I've been wrestling with this stuff for about 5 years now and gone through many permutations but reasonably happy where I am now. But stuff like destructuring is probably always going to be a problem until we can do cross module analysis through compilation. And basically invent our own reactive language like Svelte that goes beyond the components. I might do that one day.

Oh that's really interesting, the {()} and {$()} are similar to syntax I was considering. But I think I have a bit different implementation than you might expect.
My thought was this; createSignal() and props (or some equivalent of those) would always return a value wrapped in a Reactive class.
let HelloWorld = ({ name }) => {
    name instanceof Reactive; // true
    let count = createReactive(0);

    const doubleCount = reactive`@count * 2`;
    doubleCount instanceof Reactive; // true

    Reactive.get(name); // "jeff"
}

The template would be able to identify the special syntax at compile time, hoist all the reactive parts to the top, and use them to identify the dependencies/effects without executing the function (something like Reactive.onChange(name, ()=>stuff)). The limitation is that reactive values need an identifier, they can't be the output of a function (e.g. @(getName())). This makes them kind of shallow, but that actually might encourage good design practices with reactive values being defined above the JSX. It also simplifys the syntax to one character instead of something like {$(count)}.
On the flip side, if a reactive value was accidentally used in the template (e.g. count + 1)  basically would never produce the correct output. The current system would frequently produce the correct output, it just wouldn't update properly. But with a reactive class it'll which is a red flag that something is wrong. This also means there is no need for an untrack function, the Reactive.get(count) would already get the value in an untracked way.
With babel macros the template work can be done at compile time, but templated can also be inefficiently done at runtime just like other methods in Solid.

@jeff-hykin Compile time reactivity with compiling in the dependencies is one of the first things we tried for the next version of Marko(I also work on eBay's JavaScript framework). There are a few performance cliffs and we ultimately went more Svelte-like. The short of it was we were taking on a lot of the overhead of runtime reactivity and not getting all the benefits. It is infinitely more challenging admittedly to get cross-module reactivity with that but we've developed an approach.
The idea of fail-dangerous is interesting to me. See in the past fail-dangerous in a reactive system meant triggering crazy ping ponging of updates. Basically over-rendering was a problem. Now that we've done everything possible to prevent that we have the issue of losing updates. I do agree that though that proxy style hiding of reactivity does cause this to go undetected where as a special symbol or even signals (whose special syntax is() at the end in that perspective) will NaN out if you mess it up is preferable. This is a difficult tradeoff for consistency. With Solid I made the choice to not call out reactivity and let functions just fly because I wanted it to be seamless from inside the component whether the consumer passes a literal, a simple value, or a reactive one. And I didn't want the overhead of always wrapping expressions. This actually has considerable performance implications.
The only place we can really shave for more performance at this point is making fewer subscriptions and short of some compile away reactivity system that works cross-module anyone would be hard-pressed to find better performance. It would be possible to do a 1 for 1 proxy with say the DOM to do better, but that approach wouldn't scale to shared data or scheduling updates. So given the focus on performance, I like the set of tradeoffs made here.

One of the issues I have had is that by default, the child components are not reactive when a parent changes the props that are passed to that child.
The workarounds I have learned through experience are the following. Using these two workarounds I have been able to use Solid like React, but I am not still clear why I need to do these things, or why Solid isn't able to handle these automatically.

Use createComputed when a prop is passed from a reactive parent:

export function Child(props) {
  const [getSomeProp, setSomeProp] = createSignal<RowsSignal>(props.some_prop, false)

  // update the local copy whenever the parent updates
  createComputed(() => {
    setSomeProp(props.some_prop)
  })

}

Either use createState or pass false as the second argument of createSignal. This makes the child reactive.

In addition to better documentation, we probably need some Eslint rules that help us write correct Solid code. I have been using eslint-plugin-react with react/react-in-jsx-scope disabled, but still, this doesn't cover the corner cases of Solid.

In terms of a feature, would manual/explicit effects for a function be considered bloat, or could it potentially be part of Solid.js

There is an on helper(it supports arrays too). https://github.com/solidjs/solid/blob/main/documentation/api.md#on. I made a modifier since realistically you could want this behavior on any computation. But yes that is all it does. Calling everything in the same manner. I think it's fine since there is a much greater waste if you force the end-user to denote every expression as a computation, especially over component boundaries.
What's weird about that example is why the condition isn't a signal. That's one of the strengths of this sort of granularity. When the condition is false we don't even subscribe to count. If you update it every 100ms, no extra work is being done when the condition is false. Static dependencies don't solve that which is one of the challenges I've hit for compiled reactivity.

I'm a bit confused with the comments on async...
Ok I see... yeah a sort of hybrid of using the reactive system to deliver promises. That would be a pain for the compiled output the same way Observables are. Atleast Observables could stay fixed. Mostly that the expressions would need to be written a different way for promises.. ie.. if promise then it. Which we wouldn't know until runtime and autotracking doesn't know until it is running so I don't think there is a way to do this without bloating every binding. Like Solid outputs:

createEffect(() => el.setAttribute("title", state.maybePromise))

So it naive approach would need to be
createEffect(() => {
  const value = state.maybePromise
  if ("then" in value) value.then(v => el.setAttribute("title", v))
  else el.setAttribute("title", value)
})

Obviously could wrap in a helper especially since I'm missing promise cancellation here. createResource just handles this all sooner and leaves you with a signal. It does push you towards Suspense which I suspect doesn't feel flexible enough.

@aminya

One of the issues I have had is that by default, the child components are not reactive when a parent changes the props that are passed to that child.

We are still missing each other. You really don't want components to be reactive. Ever...
I think I'm missing some scenario or something you are trying to do. Is it 2-way binding? Resetable forms? Like why a local copy of state/signal to just wrap a prop when you could use the prop. Or a derived value. The problem is if possible you more than a single source of truth there will either be synchronization or indirection on read. Indirection on read might actually be a good reusable pattern as it could avoid creating additional computations. But it sounds like right now you are in a place where you are trying to work around the system and I'd like to understand why.

Not sure if relevant, but for context I've used the pattern of local state/signal which is updated when parent passed prop changes. The two use cases I had were forms (passing in new initial values post submit, whilst still allowing the form to edit values locally until submission) and drag and drop (local copy of ordering to avoid updates interfering with an in progress drag).
I use createEffect for updating the local copy when passed prop value changes.

@aminya

One of the issues I have had is that by default, the child components are not reactive when a parent changes the props that are passed to that child.

We are still missing each other. You really don't want components to be reactive. Ever...
I think I'm missing some scenario or something you are trying to do. Is it 2-way binding? Resetable forms? Like why a local copy of state/signal to just wrap a prop when you could use the prop. Or a derived value. The problem is if possible you more than a single source of truth there will either be synchronization or indirection on read. Indirection on read might actually be a good reusable pattern as it could avoid creating additional computations. But it sounds like right now you are in a place where you are trying to work around the system and I'd like to understand why.

For me, the components are a unit of code-reusability. A component allows me to make a package like solid-simple-table, and others only need to use it in their components and pass data into it.
When a component is used inside another component, the default assumption should be reactivity from the parent. I am assuming that Solid cannot perform multi-component analysis to detect this, and that's why we can't fix this automatically.
If I had a prop which I didn't need to be reactive, then I would simply destructure it.
  // static props:
  // destructure the props that are not tracked and are used inside the loop
  const {
    headerRenderer = defaultHeaderRenderer,
    bodyRenderer = defaultBodyRenderer,
    getRowID = defaultGetRowID,
    accessors,
  } = props

@martinpengellyphillips Thanks for the example. In the past (where I didn't have state at my disposal) I did similar synchronization. Generally not using a computation, but manually on the submit action or as an exposed API, but the same idea. Mostly that in my case I couldn't always guarantee that the value from above would change. Like if you are just resetting the props from the parent might not change.
This pattern of exposing an API isn't an obvious pattern and I haven't seen it as much as of late. If you pass in an object as a prop the consumer can write APIs to it. ref's can also be used this way albeit inconsistently. It might be because of React's tendency to re-render everything. But basically passing reset back up to the parent so they can call it. Alternatively the parent can just pass in a reset signal designed to always update (equals false). This isn't much different than I picture @aminya is doing in terms of having to set stuff to false except it isolates it from the data.
I suppose another approach is always to deep clone the starting data on reset and pass it in. That would guarantee updates.

@aminya

One of the issues I have had is that by default, the child components are not reactive when a parent changes the props that are passed to that child.

When a component is used inside another component, the default assumption should be reactivity from the parent. I am assuming that Solid cannot perform multi-component analysis to detect this, and that's why we can't fix this automatically.

By fix you mean simulate top-down rendering? Even with perfect analysis that wouldn't be the direction here. Props coming in are reactive and the child can react to them. I don't understand where the idea the child isn't reactive coming from. As best as I can tell the false in the original example is likely because the same value is being set. It's not changing so it's not notifying by default. Not unlike if your component was wrapped in React.memo.  Is it top-level component tracking you are after? That would be disastrous without a temporary data format. Even something like Svelte which is very component centric doesn't just re-run the top-level component you need to wrap the expressions behind $: labels. It's just a different model and probably needs to be treated as such.

The problem is to make a component that when the parent changes the props passed to it, it updates the rendering. For example, if the parent adds a new entry in the data, the table adds a new row.
solid-table.zip

parent-false-child-false-has-createComputed   ----> the only working combination. When data changes in the parent, the data of the child are updated too and rendering happens
parent-false-child-false-no-createComputed    ----> only updates if I click a button
parent-false-child-true-has-createComputed    ----> only updates if I click a button
parent-true-child-false-has-createCompute     ----> only updates if I click a button
parent-true-child-true-has-createComputed     ----> nothing happens
parent-true-child-true-no-createComputed      ---->  nothing happens (Solid's default settings)

Here is the code of the parent:
https://github.com/aminya/solid-simple-table/blob/c7b08336e22778c99ade7f6e1b4c4f7ada47a860/demo/variable-rows/index.tsx#L18-L26
Here is the code of the child (which is supposed to be a reusable component):
https://github.com/aminya/solid-simple-table/blob/c7b08336e22778c99ade7f6e1b4c4f7ada47a860/src/SimpleTable.tsx#L18-L23
If you would like to play with the example: pnpm install && pnpm run demo.variable-rows

(Coincidentally getting back on the topic of improving documentation)
I think there's a point of confusion here @aminya @ryansolid . If I'm understanding correctly, for a single instance of a component, the render function is only ever called once, and then from then on the Dom is mutated by using effects right?
So one part of @aminya's code basically has
function TableComponent(props) {
    return

       <For each={props.columns}>
            {(column) => /*stuff*/}
        </For>

}

Since  is built in we would expect the it to mutate/update it's children when props.columns changes right? (When the parent changes props.columns)

@ryansolid fyi, for my form example it's not actually a reset as such. It's a bit special to my needs, but on submit the parent handles formatting the data to a nicer display version. And then I just reuse the form for display. It's an unusual live edit form and display situation.
But this is actually what I like about solid. I end up building just what I need. I'm not tempted to try and find a formik library and then make it do what I want.

@aminya @jeff-hykin
I see. The problem is with the set call. And admittedly due to a more recent change. Mostly I wanted to address inconsistencies between signal and state, and I looked around at competitors like Vue and MobX and saw their defaults were only notify on change so I followed suit.
My new tutorials show this off a bit but you also see this in most of list examples like TodoMVC. Essentially the main reason things aren't updating is because you are setting the same array.
const rows = getRows()
rows.push({ file: "New file", message: "New message", severity: "info" })
setRows(rows) // still the same array... solid has no knowledge anything has changed

Now you can always notify by turning the equality check off like you have been doing. But generally the approach is:
setRows([...getRows(), { file: "New file", message: "New message", severity: "info" }] )  // different array

Now you won't need those false and everything will update by default.
The reason for the computed is that you are accessing the value in an untracked context.
// This initializes a new signal with the current value of props.row... no dependencies are made
const [getRows, setRows] = createSignal(props.rows, false)

createComputed(() => {    setRows(props.rows)  })

There are many ways to do things here so I can't point you at a specific solution. But once you choose to make new local state or signals you need to keep it in sync with a computation.  But you could just use it directly like @jeff-hykin example. You could use createMemo for some derived values.
If synchronization is desired, the thing I'm thinking is if it would be possible to make a primitive to handle this clone reset scenario, but I don't think it would be generic for all cases. Like if it were simply signals (no state).. I could picture a sort of writable clone...
function createClone(fn) {
  const [s, set] = createSignal();
  createComputed(() => set(fn());
  return [s, set];
}

// use like
const [getRows, setRows] = createClone(() => props.rows);

I don't know just spitballing. Many options here.
@martinpengellyphillips
Only snag is if the initialValue doesn't change. Setting it again won't retrigger. If it is consistently retriggering as desired for your scenario I don't see a problem.

My new tutorials show this off a bit but you also see this in most of list examples like TodoMVC. Essentially the main reason things aren't updating is because you are setting the same array.
const rows = getRows()
rows.push({ file: "New file", message: "New message", severity: "info" })
setRows(rows) // still the same array... solid has no knowledge anything has changed

Now you can always notify by turning the equality check off like you have been doing. But you basically have to do that everywhere. Generally, the approach is:
setRows([...getRows(), { file: "New file", message: "New message", severity: "info" }] )  // different array

Oh, I see. Is this the same for createState generated states? Can't we add a counter inside the set functions that detects the numbers that a function is called? If we could, then we can trust the user that is calling setRows, and perform a diff check.

Yes but createState is nested so you can opt to do a nested update. Like you could just set the index at the end of the array to effectively push on the new item without cloning.
In general we do not diff data. In fact diffing the signal would make no sense since the only thing that could notify is the signal itself and we can't account for all the different downstream ways it could be used. Like say we diff we know it has changed, but the downstream just gets the data and doesn't know what has changed. So we did that diffing for basically no value because presumably who ever is doing the setting could make that determination. If we wanted to always notify we could that is what the false flag is for. But if we guard by default you'd need to propagate this along the whole chain which is not a guarantee you can make as a generic API which guards by default.
Basically, the defaults make a big difference here, and when consider that effectful changes can have real side effects (we run cleanup every time they re-evaluate) restricting notification is important. An equality check in the computation is too late it needs to happen at the point that the upstream signal decides whether to notify.
So when trying to decide between guarding by default and not I landed on guarding because it is the easiest the explain and it basically removes the opt in aspect of this. When designing slightly more complicated things we'd be pretty aggressive guarding and then have to instruct the end user that we guard like this so pass in unique data. Now it's just universal. Basically well written re-usable libraries for performance reasons will be guarding for most things. And as people started writing more libraries it became harder to hide that detail or deal with the inconsistency. I sometimes opt into notify always but it's in local scopes. Like triggering something. For external facing APIs I feel notify on change is the only way to be consistent.
It does occur to me though that the result is a little strong-armed even if it is a clear message. But Vue and MobX are the same defaults. Sure you don't experience this as much because they rely a lot on the proxies, like Solid's State object. So maybe that is just the solution here.  Their state is mutable though so I bet people don't even realize it. But generally don't grab reactive data and mutate outside of the reactive system and expect it to update. It's possible in dev mode that I should be returning readonly proxies that warn people trying to mutate this data.

But generally don't grab reactive data and mutate outside of the reactive system and expect it to update

😢 that's my favorite feature of Vue. I can do something as jank as JQuery a dom element, assign element.data.name to some debugging value, and the whole system reacts like normal

To be clear if you are using a Vue proxy it isn't what I mean by outside the system. Vue's reactivity isn't doing any sort of deep diffing. It is very similar to Solid's. I default to readonly proxies but there are the ability to make mutable ones. By outside the reactive system I mean taking non-wrapped values and updating them and expecting them to change. For instance holding reference to the initial value being passed into a reactive initializer and updating it. In other cases I mean shallow reactive values. Vue I believe wraps deep by default so you probably never see this. But Solid SIgnals are shallow by default. If you are looking for Vue like behavior use createState or createMutable.

I'm still definitely struggling with knowing when a component will update (and especially what will fail to trigger an update). The differences between createState and createSignal are somewhat opaque to me.

@jcuenod I'm hoping the tutorials address that pretty well. I think we need more interactive examples to appreciate it since even explaining it doesn't really make sense when I say shallow versus nested tracking and what that means. You can give them a try here: https://dev.solidjs.com/tutorial/introduction_basics. There is some bugs in terms of navigation and loading race conditions but maybe this will help.

@ryansolid I hadn't seen <dev.solidjs.com> yet. It looks great! Yes, I have noticed some loading bugs but (other than that) I like it. I think you need to explain "tracking scopes" (at least, when I encountered the term, I didn't know what it means in practice, even though I can guess its definition).

Just saw this issue. Referencing https://github.com/solidjs/solid/issues/504

Does Solidjs support Generators in the event lifecycle?

Good call on the interopt. Bringing other libraries into Solid is pretty easy but the opposite matters completely on the mechanisms of the host framework. For client side its mostly just a ref and render call but for Next or SvelteKit, anything with SSR there isn't a definitive answer.
As for generators no. The lifecycles are a bit fake anyway. Its all just reactive subscriptions. Tracking in generators doesn't really make sense to me and unclear what we'd be yielding to. I guess the settling of the reactive system. Not sure. Probably worth some thought. I wonder if introducing them core would create potential issues for concurrent rendering.

@ryansolid I don't know if you looked into the effection library, which uses generators to have Structured Concurrency, but it got me excited about using generators to solve some issues I've been having.

Stuff when I started:

component props using getters to track usage rather than function calls. Reactivity was pretty easy to figure out for the most part after reading the reactivity guide, but it seems to be missing examples with props.
createEffect can contain onCleanup. this should probably be part of the useEffect examples, how to clean up stuff after the effect is done. Also maybe useful to note that createEffect can contain other createEffects and stuff like that.

@btakita I imagine this would be a larger change. MobX has things like flows which use generators to create actions. I can see in places where there are side effects doing that sort of thing. But Solid's own primitives are based on a queuing system so I don't really see how it would play nice.
@pfgithub
A good chunk of the rendering guide is on props(https://github.com/solidjs/solid/blob/main/documentation/guides/rendering.md#props). I didn't use an example in the reactivity side as I viewed them more as artifact of components and less reactive fundamentals but maybe that is where it would be expected?
Yeah I think I don't make that obvious. onCleanup says you can put them anywhere but doesn't really give an example of that. I used to highlight the nesting but hmm.. I don't know how much of that is reference as much as by example.
Did by chance you see the tutorials on dev.solidjs.com? I was hoping they would supplement the docs sufficiently.

@ryansolid That makes sense. Thank you for the explanation.
I am running into wanting to add an interface to the props of a component. Have not seen any examples. Perhaps something about Typescript types would be good to document.

I agree we collecting some stuff in the Discord. I'm just uncomfortable at writing it. I do not feel confident in my knowledge of TypeScript at all. Some people have contributed some very powerful typing to Solid but I feel after almost 3 years it still hasn't clicked for me.

@ryansolid Just wanted to say that video yesterday was excellent for explaining the reactivity system. I think the interview format made all the difference, and made an order of magnitude better than the current reactivity guide linked in the readme.md
Linking that video in the documentation under something like "how does Solid know what to update?" would fill the biggest documentation hole for me (and would fully address my original message on this thread)

Might be just me, but I think it would be helpful to include the import line required for each code snippet (currently done in some but not all of them)
e.g.
const [getValue, setValue] = createSignal(initialValue);

// read value
getValue();

// set value
setValue(nextValue);

// set value with a function setter
setValue(prev => prev + next);

Could be 👇
import { createSignal } from "solid-js"; // adding this line

const [getValue, setValue] = createSignal(initialValue);

// read value
getValue();

// set value
setValue(nextValue);

// set value with a function setter
setValue(prev => prev + next);

This would help for newcomers like me who don't completely get the project structure and help flying over the documentation a little faster.

I know very little of React, mostly use Vue 2/3 and kind so kind of thought give Solid a shot (React didn't really stick because of all these immutable object updates and state management libraries). So thought about implementing a json form and kind of struggling understanding how to go about nested structures that update directly and in what form should I pass props.
Let's say we have a fields that could be retrieved via ajax:
const fieldDefinitions = [
  {
    name: 'email',
    type: 'string',
    value<EMAIL_ADDRESS>  },
  {
    name: 'roles',
    type: 'entities',
    schema: [
      {
        name: 'name',
        type: 'string',
        value: '',
      },
    ],
    value: [
      [
        {
          name: 'name',
          type: 'string',
          value: 'User',
        },
      ],
    ],
  }
];

And we would just pass it to a SchemaForm element:
<SchemaForm fields={fields}/>

And it's implementation (just a sample):
const FormSchema = function (props) {
  function dummyClone(array) {
    return array.map(item => Object.assign({}, item));
  }

  return (
    <For each={props.fields}>{(field, i) => (
      <Switch>
        <Match when={field.type === 'string'}>
          <input
            class="form-control"
            name={field.name}
            value={field.value}
            onInput={e => field.value = e.currentTarget.value}
          />

          Value Is Reactive: {field.value}
        </Match>
        <Match when={field.type === 'entities'}>

{field.name}

          <For each={field.value}>{(entry, i) => (<>
            <FormSchema fields={entry}/>
            <button type="button" onClick={() => field.value.splice(i(), 1)}>Remove</button>
          </>)}</For>

          <button type="button" onClick={() => field.value.push(dummyClone(field.schema))}>Add</button>
        </Match>
      </Switch>
    )}</For>
  );
};

What's the reasonable way to pass fields into the SchemaForm? Store? Mutable? How should it then update the value? add and remove entries from entities type fields? I know with React you kind of emit an event with the path and value to the controlling component but what would be your vision to implement this?
All the samples so far were dealing with data structure you know and shallow tree but kind of wish there were samples of dealing with recursive data and their mutation. What would be the preferred Solid way?

I think I've got a question that I really cannot understand. But it's only very-minor conceptional variable-naming type question, but I think it would be cool to explain that (at least here, because I didn't find any answer in the internet so far)
Why state is called signal in SolidJS?
I understand that each framework has it's own terminology and ideas and developer should have specific mindset in order to use a framework properly, but I guess that most of developers today agree, that each component can have some sort of... state. Or stateful data. It's a common concept across frameworks and it's pretty straightforward and easy to understand and conceit, because this term is also applicable to other domains.
But... signal?
It doesn't tell me anything and without documentation I wouldn't even know what createSignal does and what is it for (despite being one of the most fundamental and crucial functions in this framework)

Lots of frameworks have terms that aren't obvious that require reading documentation. In some cases the word and meaning between frameworks and patterns even overlap further adding to confusion. So consolidating terminology to align with other broad concepts isn't the strongest argument for calling it createState.
From a personal preference perspective I rather like signal, it gives Solid a bit more distinct of an API and also I feel like the word expresses the mechanical reactive nature of the primitive. When the value changes it signals a change in reactivity.
State to me is a much broader term involving more than one part of the application. Ie state could encompass multiple components. This definition could be flawed but it's how I've developed my own mental model around Solids differences.

I've found a few bumps in the road learning Solidjs from the documentation that I think would really help people adapt more easily:

More documentation on the solid-app-router documentation. I still have a problem with using useNavigation(), but there is so little to troubleshoot off of.
The classList utility is really great but you cannot pass in the variables from a CSS module, (such as styles.container for example). You have to treat the classes just as strings and import a plain CSS file separately. Not sure if this functionality is a future goal, but I'd let users know about the gotcha.
If it is possible to merge 'solid-js/web' packages into simply 'solid-js' for the sake of imports, I think it would help documentation and developer experience. Otherwise, it would be good to clarify the import module without having to search for it in Tutorials. Suppose it only applies to render and Portal from what I notice. Might save someone a headache one day

@KyleFontenot can you elaborate on #2? I've never heard any issues with CSS Modules.
We won't mix the imports since Solid can support other non-web platforms. render, Portal, Dynamic, hydrate on the browser side, and then all the renderToString pipeToNodeWritable etc.. server side. Some are exported from both locations but I agree the best course is updating the docs.
The Router does need much better docs. More it needs guides. The API isn't that large but so much in how you use them.

@KyleFontenot can you elaborate on #2? I've never heard any issues with CSS Modules.
We won't mix the imports since Solid can support other non-web platforms. render, Portal, Dynamic, hydrate on the browser side, and then all the renderToString pipeToNodeWritable etc.. server side. Some are exported from both locations but I agree the best course is updating the docs.
The Router does need much better docs. More it needs guides. The API isn't that large but so much in how you use them.

Thanks for hearin me out!
// Component.module.css file
.container {
    outline:blue;
}

import styles from './Component.module.css'
const Component = (props) => {
    // styles.container throws an error.

    const containerStyle = styles.container;

    // can set a new variable for passing it in to quiet the error, but it just parses containerStyle as "containerStyle" in the DOM

}

Unless there's something with syntax I'm missing

Yeah you can use:
import styles from './Component.module.css'
const Component = (props) => {

}

This JavaScript syntax lets you use a variable as a key to an object. In your other example it was setting containerStyle literally. To use a variable you need to use a special syntax.

@ryansolid @KyleFontenot

If it is possible to merge 'solid-js/web' packages into simply 'solid-js' for the sake of imports

While I agree with Ryan on this one, I think there might be a solution to both.
Would it be possible to have 'solid-js/web' simply export all the values from 'solid-js'? It would need to ensure no namespace collision, but other than that it would allow the web side to have a single import, while also keeping 'solid-js' web agnostic

Personally I'm happy with "never destructure reactive props or else they'll break". I usually tend to use use p.someProp anyways, I just wanted to be clear on the behaviour. That said, I suppose a helper wouldn't hurt if one is really committed to destructuring.

Stating something like "never destructure" in the docs would have saved me hours 😅. I searched the docs using google and couldn't find any mention of it:
site:solidjs.com "never destructure"

@jsdevtom Like header worthy(outside of the FAQ) I guess? It's mention 5 times in the getting started section and 4 times in the docs. People have mentioned not seeing it though so it clearly isn't present enough. I feel like I mention it in every paragraph, but I get that.

Ooh yes, I see that now. It's my fault for not reading the ... manual. I was rapidly trying to prototype with Solid because I didn't have the luxury of time. I assume others do the same thing. Perhaps UX could help. Something like an inline warning ~ https://design-system.service.gov.uk/components/warning-text/. Just a suggestion. As I said, it's my fault. It could help other (time strapped) individuals, though.

I think when a developer goes to docs, the first thing they see should not be "Basic Reactivity" and "createSignal". Because these terms might not mean anything to me. There should be a getting started at the top of documentation.

The intention was the "Getting Started" section to handle that. But maybe it's a naming thing. That section is more of an API reference and should be named as such.

I recently started using the ESLint plugin for Solid, and one of the reoccurring errors is reactive variable 'p' should be used within a tracked scope and This function should be passed to a tracked scope because it contains reactivity., and I'm not entirely sure how to handle this.
Example:
const MenuTrigger = (props: ComponentProps<"button">) => {
	const [p, rest] = splitProps(props, ["ref"])
	const composedTriggerRef = createComposedRefs(p.ref) // reactive variable 'p' should be used within a tracked scope

	// return ...
}

const MenuTrigger = (props: ComponentProps<"button">) => {
	const [p, rest] = splitProps(props, ["ref"])
	const composedTriggerRef = createComposedRefs(() => p.ref) // This function should be passed to a tracked scope because it contains reactivity

	// return ...
}

I think more information on some of the things that you can't do in solid that people might be used to from react - for example, top-level markup conditionals in a component.

I think more information on some of the things that you can't do in solid that people might be used to from react - for example, top-level markup conditionals in a component.

Do other frameworks do this as well? Mind linking us so we have an idea?

I mean React supports top-level conditionals and early returns. The core team suggests that it is bad pattern but people still do it. You will find enough React code that does without looking hard. Frameworks with Template DSLs don't have the ability to do this so really this is a Solid-only problem from a certain perspective. It's obvious to us who understand the execution model but someone coming from React, Angular, Vue, Svelte, Ember, Inferno, etc would have never experienced this. It's probably worth mentioning the same way prop destructuring is.

I think a "Thinking in Solid for a React/Preact developer" is probably what's best to have, and explain how the mental model and execution model is different. All the gotchas.

@nksaraf There's a starting point: https://github.com/teknologi-umum/solidjs-for-x-developer/blob/main/React.md

@millette that's a really nice format! Clear and concise with nice references to the docs directly. @Jutanium would appreciate this!

This issue has been great and has allowed not only better docs for Solid but the formation of a docs team. I feel like it has run its course though and I appreciate all the suggestions the last 2 years. Now that we have a dedicated organization and repo for docs all future suggestions should go there. https://github.com/solidjs/solid-docs
Thank you so much for making learning Solid more enjoyable.


CSUB-368:  Add unit tests for staking extrinsics

Description of proposed changes:
Practical tips for PR review & merge:

[ ] All GitHub Actions report PASS
[ ] Newly added code/functions have unit tests

[ ] Coverage tools report all newly added lines as covered
[ ] The positive scenario is exercised
[ ] Negative scenarios are exercised, e.g. assert on all possible errors
[ ] Assert on events triggered if applicable
[ ] Assert on changes made to storage if applicable

[ ] Modified behavior/functions - try to make sure above test items are covered
[ ] Integration tests are added if applicable/needed

Codecov Report

Merging #887 (130d27d) into dev (fd1e262) will decrease coverage by 2.63%.
The diff coverage is 46.09%.

@@            Coverage Diff             @@
##              dev     #887      +/-   ##
==========================================
- Coverage   78.24%   75.62%   -2.63%
==========================================
  Files          68       80      +12
  Lines       10726    11551     +825
==========================================
+ Hits         8393     8735     +342
- Misses       2333     2816     +483

Impacted Files
Coverage Δ

pallets/difficulty/src/lib.rs
93.05% <ø> (ø)

pallets/staking/src/slashing.rs
0.00% <0.00%> (ø)

primitives/src/lib.rs
93.33% <ø> (ø)

runtime/src/lib.rs
24.13% <0.00%> (+0.35%)
:arrow_up:

pallets/staking/src/ledger.rs
27.83% <27.83%> (ø)

pallets/staking/src/pallet/mod.rs
27.92% <28.24%> (ø)

pallets/staking/src/pallet/impls.rs
38.65% <38.65%> (ø)

pallets/task-voting/src/mock.rs
53.48% <52.38%> (ø)

pallets/staking/src/lib.rs
26.47% <55.55%> (ø)

pallets/staking/src/era.rs
80.32% <80.32%> (ø)

... and 12 more

:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more

Implementation has changed so this is no longer valid.