@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 |