Update Docs

[DavidJFelix]

Hey 👋🏻 I noticed that you renamed the project and created a documentation site. I wanted to say that I think this is a great improvement and a big step forward. I also noticed that it looks like there is further support for non-jotai and non-react frameworks. I've been playing with jotai-molecules (now bunshi!!) at work and I wanted to try to share some of my experience in the form of updating documentation.

Anyways, I'm opening this docs ticket to try to track some of the in-flight PRs I intend to open to improve documentation and add examples:

• [ ] Consistent naming rules
  • [ ] Bunshi - always capitalized or only at the beginning of setences?
  • [ ] Molecules / Scope - should the concept be capitalized?
  • [ ] Code examples - scope and molecule naming, capitalized?
• [ ] Decide on consistent documentation naming of molecule parameters
  • [ ] Don't want to shadow molecule
  • [ ] Is getMolecule or getScope too verbose?
  • [ ] Is mol or scope clear that its adding a dependency?
  • [ ] Do we want to introduce alternate names to demonstrate that position is the only thing that dictates the names and users can use shorthand however they want?
• [ ] Look into the overall structure of docs.
  • [ ] On Quickstart, link to concept pages after a shallow introduction
  • [ ] On Quickstart, Demonstrate using scope from both react and vue
• [ ] Provide further example code for scoping more complex interactions
• [ ] Opinionated guidance for structuring and organizing molecules
• [ ] Scope as a mechanism for parameterizing atoms (for example: jotai-tanstack-query)
• [ ] Create integrations section
  • [ ] Nanostores examples section
  • [ ] React examples section
  • [ ] Scope as a mechanism to initialize atoms from react-tree state
  • [ ] Zustand examples section

If anyone thinks of anything they'd like to see improved, I can help with adding it to this meta-issue and try to break out more meaningful and specific examples for some of the broader goals here. Expect some PRs in the future tied to this.

And thanks again!

[loganvolkers]

Thanks for the feedback @DavidJFelix -- I agree that more examples and documentation is definitely due. The API is intentionally small, and the possibilities are all in the different use cases and examples.

Very open to more documentation, please don't hesitate to contribute.

One thing I'd like to see is an easy way to write documentation that is also runnable, similar to what Jotai docs do with CodeSandbox examples, but ideally without losing a centralized repository of code to prevent examples becoming out of date.

[DavidJFelix]

I wonder if something like https://github.com/kevin940726/remark-codesandbox could keep sandboxes up to date with docs

[DavidJFelix]

Here's an example I've been working on from the original jotai example that I think helps showcase counter scoping better than the original:

import React, { useId } from "react";
import { atom, useAtom } from "jotai";
import {
  molecule,
  useMolecule,
  createScope,
  ScopeProvider
} from "jotai-molecules";

const counterOwnerScope = createScope("");
const counterParamsScope = createScope({ initialCount: 0 });

const counterParamsMolecule = molecule((_getMolecule, getScope) => {
  const params = getScope(counterParamsScope);
  return params;
});

const ownedCounterMolecule = molecule((getMolecule, getScope) => {
  getScope(counterOwnerScope);
  const { initialCount } = getMolecule(counterParamsMolecule);
  return atom(initialCount);
});

const useOwnedCounter = () => {
  const countAtom = useMolecule(ownedCounterMolecule);
  const [count, setCount] = useAtom(countAtom);

  return [count, setCount] as const;
};

const Counter = () => {
  const [count, setCount] = useOwnedCounter();
  return (
    <div>
      {count} <button onClick={() => setCount((c) => c + 1)}>+1</button>
    </div>
  );
};

const CounterOwnerScope = ({
  value,
  children
}: {
  value: string;
  children: React.ReactNode;
}) => (
  <ScopeProvider scope={counterOwnerScope} value={value}>
    {children}
  </ScopeProvider>
);

const App = () => {
  const id0 = useId();
  const id1 = useId();
  return (
    <div>
      <CounterOwnerScope value={id0}>
        <h1>Outer id0</h1>
        <Counter />
        <CounterOwnerScope value={id1}>
          <h1>id 1</h1>
          <Counter />
        </CounterOwnerScope>
        <ScopeProvider scope={counterOwnerScope} value={id0}>
          <h1>Inner id 0</h1>
          <ScopeProvider scope={counterParamsScope} value={{ initialCount: 1 }}>
            <Counter />
          </ScopeProvider>
          <Counter />
        </ScopeProvider>
      </CounterOwnerScope>
    </div>
  );
};

export default App;

[loganvolkers]

Thanks for the PRs @DavidJFelix, I'll get to reviewing and approve them next week when I'm back from vacation.

[loganvolkers]

I wonder if something like https://github.com/kevin940726/remark-codesandbox could keep sandboxes up to date with docs

Looks like Sandpack is the best tool for the integrated docs. Requires some tinkering to get it working perfectly, but it's looking promising. See the WIP branch https://github.com/saasquatch/bunshi/tree/sandpack

[DavidJFelix]

Thanks for the PRs @DavidJFelix, I'll get to reviewing and approve them next week when I'm back from vacation.

No worries -- I'm slowly working thru meta-issue this but paused after these because my commits will stack and I didn't want to create more trouble by staging stacking, so I'll rebase on any changes later. Enjoy vaca