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?
    • Always capitalized when talking about the library, not capitalized when talking about the Japanese word.
  • Molecules / Scope - should the concept be capitalized?
    • Normal casing rules apply. Sentence case / title case
  • Code examples - scope and molecule naming, capitalized?
    • Normal casing rules
• 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

[loganvolkers]

@DavidJFelix new docs are out, lots of recipes added and working examples powered by Sandpack.

Please rebase and looking forward to your contributions!

[loganvolkers]

@DavidJFelix thoughts and feedback on the new recipes?

[DavidJFelix]

I think the new recipes look great! Still need to get around to the feedback -- got swamped around the holidays.

[loganvolkers]

@DavidJFelix check out the new use function in 2.1.0 and the updated docs on molecule lifecycle and see if your TODO list is getting closer to compete.

Feel free to reprioritize a TODO list, I appreciate the outside perspective.

[DavidJFelix]

Will do -- sorry for the long delay, I'm working on getting bunshi into use at work and trying to see where I notice blindspots. I'll take a look!

[loganvolkers]

I appreciate your contributions, on whatever timeline they take.