feat: new hooks and actions APIs

.changeset/petite-actors-lie.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/angular-store': minor
+'@tanstack/preact-store': minor
+'@tanstack/svelte-store': minor
+'@tanstack/react-store': minor
+'@tanstack/solid-store': minor
+'@tanstack/vue-store': minor
+'@tanstack/store': minor
+---
+
+chore: update deps and change build process to tsdown

docs/config.json

@@ -176,8 +176,36 @@
               "to": "framework/react/reference/index"
             },
             {
-              "label": "Functions / useStore",
-              "to": "framework/react/reference/functions/useStore"
+              "label": "Functions / createStoreContext",
+              "to": "framework/react/reference/functions/createStoreContext"
+            },
+            {
+              "label": "Functions / useCreateAtom",
+              "to": "framework/react/reference/functions/useCreateAtom"
+            },
+            {
+              "label": "Functions / useValue",
+              "to": "framework/react/reference/functions/useValue"
+            },
+            {
+              "label": "Functions / useSetValue",
+              "to": "framework/react/reference/functions/useSetValue"
+            },
+            {
+              "label": "Functions / useAtom",
+              "to": "framework/react/reference/functions/useAtom"
+            },
+            {
+              "label": "Functions / useCreateStore",
+              "to": "framework/react/reference/functions/useCreateStore"
+            },
+            {
+              "label": "Functions / useSelector",
+              "to": "framework/react/reference/functions/useSelector"
+            },
+            {
+              "label": "Variables / useStore (deprecated)",
+              "to": "framework/react/reference/variables/useStore"
             },
             {
               "label": "Functions / shallow",

docs/framework/react/quick-start.md

@@ -8,7 +8,7 @@ The basic react app example to get started with the TanStack react-store.
 ```tsx
 import React from "react";
 import ReactDOM from "react-dom/client";
-import { createStore, useStore } from "@tanstack/react-store";
+import { createStore, useSelector } from "@tanstack/react-store";
 
 // You can instantiate the store outside of React components too!
 export const store = createStore({
@@ -19,7 +19,7 @@ export const store = createStore({
 // This will only re-render when `state[animal]` changes. If an unrelated store property changes, it won't re-render
 
 const Display = ({ animal }) => {
-  const count = useStore(store, (state) => state[animal]);
+  const count = useSelector(store, (state) => state[animal]);
   return <div>{`${animal}: ${count}`}</div>;
 };
 
@@ -55,3 +55,5 @@ const root = ReactDOM.createRoot(document.getElementById("root"));
 root.render(<App />);
 
 ```
+
+`useStore` remains available as a deprecated alias to `useSelector`.

docs/framework/react/reference/functions/createStoreContext.md

@@ -0,0 +1,92 @@
+---
+id: createStoreContext
+title: createStoreContext
+---
+
+# Function: createStoreContext()
+
+```ts
+function createStoreContext<TValue>(): object;
+```
+
+Defined in: [react-store/src/createStoreContext.ts:40](https://github.com/TanStack/store/blob/main/packages/react-store/src/createStoreContext.ts#L40)
+
+Creates a typed React context for sharing a bundle of atoms and stores with a subtree.
+
+The returned `StoreProvider` only transports the provided object through
+React context. Consumers destructure the contextual atoms and stores, then
+compose them with the existing hooks like [useSelector](useSelector.md),
+[useValue](useValue.md), [useSetValue](useSetValue.md), and [useAtom](useAtom.md).
+
+The object shape is preserved exactly, so keyed atoms and stores remain fully
+typed when read back with `useStoreContext()`.
+
+## Type Parameters
+
+### TValue
+
+`TValue` *extends* `object`
+
+## Returns
+
+`object`
+
+### StoreProvider()
+
+```ts
+StoreProvider: (props) => ReactElement;
+```
+
+#### Parameters
+
+##### props
+
+###### children?
+
+`ReactNode`
+
+###### value
+
+`TValue`
+
+#### Returns
+
+`ReactElement`
+
+### useStoreContext()
+
+```ts
+useStoreContext: () => TValue;
+```
+
+#### Returns
+
+`TValue`
+
+## Example
+
+```tsx
+const { StoreProvider, useStoreContext } = createStoreContext<{
+  countAtom: Atom<number>
+  totalsStore: Store<{ count: number }>
+}>()
+
+function CountButton() {
+  const { countAtom, totalsStore } = useStoreContext()
+  const count = useValue(countAtom)
+  const total = useSelector(totalsStore, (state) => state.count)
+
+  return (
+    <button
+      type="button"
+      onClick={() => totalsStore.setState((state) => ({ ...state, count: state.count + 1 }))}
+    >
+      {count} / {total}
+    </button>
+  )
+}
+```
+
+## Throws
+
+When `useStoreContext()` is called outside the matching `StoreProvider`.

docs/framework/react/reference/functions/shallow.md

@@ -9,7 +9,7 @@ title: shallow
 function shallow<T>(objA, objB): boolean;
 ```
 
-Defined in: [index.ts:5](https://github.com/TanStack/store/blob/main/packages/react-store/src/index.ts#L5)
+Defined in: [react-store/src/shallow.ts:1](https://github.com/TanStack/store/blob/main/packages/react-store/src/shallow.ts#L1)
 
 ## Type Parameters
 

docs/framework/react/reference/functions/useAtom.md

@@ -0,0 +1,43 @@
+---
+id: useAtom
+title: useAtom
+---
+
+# Function: useAtom()
+
+```ts
+function useAtom<TValue>(atom, options?): [TValue, (fn) => void & (value) => void];
+```
+
+Defined in: [react-store/src/useAtom.ts:17](https://github.com/TanStack/store/blob/main/packages/react-store/src/useAtom.ts#L17)
+
+Returns the current atom value together with a stable setter.
+
+This is the writable-atom convenience hook for components that need to both
+read and update the same atom.
+
+## Type Parameters
+
+### TValue
+
+`TValue`
+
+## Parameters
+
+### atom
+
+`Atom`\<`TValue`\>
+
+### options?
+
+[`UseSelectorOptions`](../interfaces/UseSelectorOptions.md)\<`TValue`\>
+
+## Returns
+
+\[`TValue`, (`fn`) => `void` & (`value`) => `void`\]
+
+## Example
+
+```tsx
+const [count, setCount] = useAtom(countAtom)
+```

docs/framework/react/reference/functions/useCreateAtom.md

@@ -0,0 +1,86 @@
+---
+id: useCreateAtom
+title: useCreateAtom
+---
+
+# Function: useCreateAtom()
+
+## Call Signature
+
+```ts
+function useCreateAtom<T>(getValue, options?): ReadonlyAtom<T>;
+```
+
+Defined in: [react-store/src/useCreateAtom.ts:17](https://github.com/TanStack/store/blob/main/packages/react-store/src/useCreateAtom.ts#L17)
+
+Creates a stable atom instance for the lifetime of the component.
+
+Pass an initial value to create a writable atom, or a getter function to
+create a readonly derived atom. This hook mirrors the overloads from
+createAtom, but ensures the atom is only created once per mount.
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### getValue
+
+(`prev?`) => `T`
+
+#### options?
+
+`AtomOptions`\<`T`\>
+
+### Returns
+
+`ReadonlyAtom`\<`T`\>
+
+### Example
+
+```tsx
+const countAtom = useCreateAtom(0)
+```
+
+## Call Signature
+
+```ts
+function useCreateAtom<T>(initialValue, options?): Atom<T>;
+```
+
+Defined in: [react-store/src/useCreateAtom.ts:21](https://github.com/TanStack/store/blob/main/packages/react-store/src/useCreateAtom.ts#L21)
+
+Creates a stable atom instance for the lifetime of the component.
+
+Pass an initial value to create a writable atom, or a getter function to
+create a readonly derived atom. This hook mirrors the overloads from
+createAtom, but ensures the atom is only created once per mount.
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### initialValue
+
+`T`
+
+#### options?
+
+`AtomOptions`\<`T`\>
+
+### Returns
+
+`Atom`\<`T`\>
+
+### Example
+
+```tsx
+const countAtom = useCreateAtom(0)
+```

docs/framework/react/reference/functions/useCreateStore.md

@@ -0,0 +1,78 @@
+---
+id: useCreateStore
+title: useCreateStore
+---
+
+# Function: useCreateStore()
+
+## Call Signature
+
+```ts
+function useCreateStore<T>(getValue): ReadonlyStore<T>;
+```
+
+Defined in: [react-store/src/useCreateStore.ts:17](https://github.com/TanStack/store/blob/main/packages/react-store/src/useCreateStore.ts#L17)
+
+Creates a stable store instance for the lifetime of the component.
+
+Pass an initial value to create a writable store, or a getter function to
+create a readonly derived store. This hook mirrors the overloads from
+createStore, but ensures the store is only created once per mount.
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### getValue
+
+(`prev?`) => `T`
+
+### Returns
+
+`ReadonlyStore`\<`T`\>
+
+### Example
+
+```tsx
+const counterStore = useCreateStore({ count: 0 })
+```
+
+## Call Signature
+
+```ts
+function useCreateStore<T>(initialValue): Store<T>;
+```
+
+Defined in: [react-store/src/useCreateStore.ts:20](https://github.com/TanStack/store/blob/main/packages/react-store/src/useCreateStore.ts#L20)
+
+Creates a stable store instance for the lifetime of the component.
+
+Pass an initial value to create a writable store, or a getter function to
+create a readonly derived store. This hook mirrors the overloads from
+createStore, but ensures the store is only created once per mount.
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### initialValue
+
+`T`
+
+### Returns
+
+`Store`\<`T`\>
+
+### Example
+
+```tsx
+const counterStore = useCreateStore({ count: 0 })
+```