@assistant-ui/store#
Tap-based state management with React Context integration.
Quick Start#
import { resource, tapState } from "@assistant-ui/tap";
import { useAui, useAuiState, AuiProvider, type ClientOutput } from "@assistant-ui/store";
// 1. Define client type
declare module "@assistant-ui/store" {
interface ScopeRegistry {
counter: { methods: { getState: () => { count: number }; increment: () => void } };
}
}
// 2. Create resource
const CounterClient = resource((): ClientOutput<"counter"> => {
const [state, setState] = tapState({ count: 0 });
return { getState: () => state, increment: () => setState({ count: state.count + 1 }) };
});
// 3. Use in React
function App() {
const aui = useAui({ counter: CounterClient() });
return <AuiProvider value={aui}><Counter /></AuiProvider>;
}
function Counter() {
const count = useAuiState((s) => s.counter.count);
const aui = useAui();
return <button onClick={() => aui.counter().increment()}>{count}</button>;
}
Concepts#
Clients: Named state containers registered via module augmentation.
declare module "@assistant-ui/store" {
interface ScopeRegistry {
myClient: {
methods: MyMethods; // must include getState(): MyState
meta?: { source: "parent"; query: { id: string } };
events?: { "myClient.updated": { id: string } };
};
}
}
Derived Clients: Access nested clients from parents.
useAui({
item: Derived({ source: "list", query: { index: 0 }, get: (aui) => aui.list().item({ index: 0 }) }),
});
Events:
const emit = tapAssistantEmit();
emit("myClient.updated", { id: "123" });
useAuiEvent("myClient.updated", (p) => console.log(p.id));
API#
| Hook/Component | Description |
|---|---|
useAui() | Get client from context |
useAui(clients) | Create/extend client |
useAuiState(selector) | Subscribe to state |
useAuiEvent(event, cb) | Subscribe to events |
AuiProvider | Provide client to tree |
AuiIf | Conditional rendering |
| Tap Utility | Description |
|---|---|
tapAssistantClientRef() | Access client ref in resources |
tapAssistantEmit() | Emit events from resources |
tapClientResource(element) | Wrap resource for event scoping (1:1 mappings) |
tapClientLookup(map, fn, deps) | Lookup by {index} or {key} |
tapClientList(config) | Dynamic list with add/remove |
attachTransformScopes(resource, fn) | Attach scope transform |
| Type | Description |
|---|---|
ClientOutput<K> | Resource return type (methods object) |
ScopeRegistry | Module augmentation interface |
AssistantClient | Full client type |