@servicetitan/docs-anvil-uikit-contrib 38.7.0 → 39.0.0

package/docs/tanstack-query-mobx/01-queries.mdx

@@ -0,0 +1,187 @@
+---
+title: Queries
+---
+
+# Queries
+
+Queries are **data-driven** — they run automatically based on their options, not by explicit calls. When a store initializes, its queries subscribe to the TanStack client and begin fetching. Changes to `queryKey` values trigger refetches via MobX reactivity.
+
+## Creating Queries
+
+### Composable (recommended)
+
+Use the `query()` factory as a class field with a function `() => ({...})`. MobX tracks observable dependencies accessed inside the function and triggers refetch when they change.
+
+```tsx
+@queryStore
+class JobsStore extends Store {
+    @inject(JobsApi) private api?: JobsApi;
+    @observable selectedJobId = 0;
+
+    jobs = query<Job[]>(() => ({
+        queryKey: ['scheduling', 'jobs', this.selectedJobId],
+        queryFn: async () => (await this.api?.getJobs(this.selectedJobId))?.data ?? [],
+        enabled: this.selectedJobId > 0,
+    }));
+
+    techs = query<Tech[]>(() => ({
+        queryKey: ['scheduling', 'techs'],
+        queryFn: async () => (await this.api?.getTechs())?.data ?? [],
+    }));
+}
+```
+
+Multiple queries are just additional class fields — no special API needed.
+
+> **Note:** `query()` also accepts a plain object `query({...})` instead of a function, but this is evaluated once at class field initialization and won't react to observable changes. Use the function form unless you have a reason not to.
+
+### Inheritance
+
+Use the `queryOptions` getter for the primary query, and `addQuery()` for additional queries.
+
+```tsx
+@injectable()
+class JobsStore extends QueryApiStore<Job[]> {
+    @inject(JobsApi) private api?: JobsApi;
+
+    get queryOptions(): QueryApiOptions<Job[]> {
+        return {
+            queryKey: ['scheduling', 'jobs'],
+            queryFn: async () => (await this.api?.getJobs())?.data ?? [],
+        };
+    }
+
+    techs = this.addQuery<Tech[]>(() => ({
+        queryKey: ['scheduling', 'techs'],
+        queryFn: async () => (await this.api?.getTechs())?.data ?? [],
+    }));
+}
+```
+
+## Query Options
+
+### queryKey (required)
+
+Array of serializable values that uniquely identifies the query.
+
+- Use at least two entries — the first as a **namespace** string (e.g., `'scheduling'`, `'myapp'`) to scope and organize queries
+- Changes to any value in the key trigger a refetch (data-driven query)
+- Multiple stores with the same key share one cache and one network request (deduplication)
+- If data is already cached for a key, new subscribers get the cached data immediately (respecting `staleTime`)
+
+```tsx
+queryKey: ['scheduling', 'jobs'],              // namespace + resource
+queryKey: ['scheduling', 'jobs', jobId],       // refetches when jobId changes
+queryKey: ['scheduling', 'jobs', [...ids].sort()], // sort arrays so [1,2] and [2,1] hit the same cache
+```
+
+### queryFn (required)
+
+Async function that fetches and returns data. Can use any mechanism — Axios, fetch, generated API functions, or just return a value.
+
+```tsx
+queryFn: async () => (await this.api?.getJobs())?.data ?? [],
+```
+
+If the function depends on data like an ID, include that data in `queryKey` so the function re-runs when it changes.
+
+### enabled
+
+Boolean, defaults to `true`. The query only runs when `enabled` is `true`. Toggling from `false` to `true` triggers a fetch.
+
+```tsx
+enabled: this.selectedJobId > 0, // wait until an ID is selected
+```
+
+### staleTime
+
+Milliseconds before cached data is considered stale. Default: **10 minutes** (set by `QueryClientStore`).
+
+- **`Infinity`** — data never goes stale. Only one fetch per key, no matter how many stores subscribe. Refetch only via manual `refetch()` or `invalidate()`.
+- **`0`** — data is always stale. Every new subscriber or key change triggers a refetch.
+- **`10 * 60 * 1000` (default)** — data is fresh for 10 minutes. New subscribers within that window get cached data without refetching.
+
+Stale queries re-fetch on **fetch events**: a new store subscribing with the same key, or a `queryKey` value changing. Re-fetches are deduplicated — only one network request per key at a time.
+
+### gcTime (garbage collection)
+
+Milliseconds before an **inactive** query is garbage collected. Default: **5 minutes**. A query becomes inactive when nothing is subscribed to it — either because the store unmounted, or because a reactive `queryKey` change shifted the observer to a different key.
+
+### retry
+
+Number of retry attempts for failed queries. Default: **3** with exponential backoff.
+
+### refetchInterval
+
+Number or function. When set, refetches at the specified interval. The interval resets after each refresh.
+
+See all options at [TanStack Query useQuery reference](https://tanstack.com/query/v5/docs/framework/react/reference/useQuery).
+
+## Integration-Specific Options
+
+These are additions to TanStack's standard options:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `disposeQuery` | `undefined` | Remove the query from the client cache on dispose. `true` = exact key, number = first N key segments |
+| `autoInitialize` | `true` | Set `initialized` to `true` after first successful fetch. Set to `false` to control it manually |
+| `onSuccess` | `undefined` | Callback with query data after success. Also fires on `updateQueryData()` |
+| `onError` | `undefined` | Callback with error object after failure (after retries) |
+| `globalClient` | `undefined` | Use a shared page or app-level query client. See [Shared Clients](./04-shared-clients) |
+
+## Query State
+
+Each query exposes observable state:
+
+| Flag | When `true` |
+|------|-------------|
+| `initialized` | After the first query attempt settles (package-specific, not in TanStack) |
+| `isPending` | No settled result yet — includes disabled queries that have never run |
+| `isLoading` | First fetch in flight (`isFetching && isPending`) — use for initial loading UI |
+| `isFetching` | Any fetch in flight, including background refetches |
+| `isRefetching` | Background refetch after data already exists |
+| `isSuccess` | Query succeeded |
+| `isError` | Query failed (after retries) |
+
+**Which to use:**
+- **Initial loading spinner**: `!initialized` — false until the first query attempt settles
+- **Background refresh indicator**: `isRefetching`
+- **Error handling**: `isError` + `error`
+
+## Query Methods
+
+| Method | Description |
+|--------|-------------|
+| `invalidate()` | Mark query as stale and refetch. Supports `dedupe` option to skip if already invalidated |
+| `refetch()` | Manually re-run the query |
+| `updateQueryData(data)` | Update cache without fetching. Triggers `onSuccess` |
+| `cancel()` | Cancel an in-flight request |
+| `getQueryState()` | Get the full TanStack query state object |
+
+## Runtime Queries
+
+For queries created after initialization (e.g., in response to user actions), use `setupRuntimeQueries()`:
+
+```tsx
+import { setupRuntimeQueries } from '@servicetitan/tanstack-query-mobx/composable';
+
+@queryStore
+class DetailsStore extends Store {
+    private queries = setupRuntimeQueries();
+
+    loadDetails(id: number) {
+        // Second arg is the key — calling add() again with the same key returns the existing query
+        return this.queries.add<Details>(() => ({
+            queryKey: ['details', id],
+            queryFn: () => this.api?.getDetails(id),
+        }), ['details', id]);
+    }
+
+    getDetails(id: number) {
+        // Retrieve a previously created query by key
+        return this.queries.get<Details>(['details', id]);
+    }
+}
+```
+
+Queries created via `.add()` are automatically set up with the store's query client and disposed when the store disposes. The key serves two purposes: `.add()` returns the existing query if one was already created with that key, and `.get()` retrieves it later.

package/docs/tanstack-query-mobx/02-mutations.mdx

@@ -0,0 +1,141 @@
+---
+title: Mutations
+---
+
+# Mutations
+
+Mutations are for updating, creating, or deleting data. Unlike queries, mutations are **called manually** via `runMutation()`. They can automatically invalidate (refetch) related queries after success.
+
+## Creating Mutations
+
+### Composable (recommended)
+
+Use the `mutation()` factory as a class field:
+
+```tsx
+@queryStore
+class TasksStore extends Store {
+    @inject(TasksApi) private api?: TasksApi;
+
+    snooze = mutation<void, { id: number; note?: string }>(() => ({
+        mutationFn: async (arg) => (await this.api?.snooze(arg.id, arg.note))?.data,
+        invalidatedQueries: [['myapp', 'tasks'], ['myapp', 'progress-tracker']],
+        onSuccess: () => {
+            toast.success({ title: 'Task Snoozed', message: 'We will check back soon.' });
+        },
+        onError: error => {
+            toast.danger({ title: 'Task Snooze', message: error.message });
+        },
+    }));
+
+    handleSnoozed = async (id: number, note?: string) => {
+        await this.snooze.runMutation({ id, note });
+    };
+}
+```
+
+### Inheritance
+
+Use `addMutation()` on the store:
+
+```tsx
+@injectable()
+class TasksStore extends QueryApiStore<Task[]> {
+    @inject(TasksApi) private api?: TasksApi;
+
+    snooze = this.addMutation<void, { id: number; note?: string }>(() => ({
+        mutationFn: async (arg) => (await this.api?.snooze(arg.id, arg.note))?.data,
+        invalidatedQueries: [['myapp', 'tasks']],
+    }));
+}
+```
+
+## Mutation Options
+
+### mutationKey
+
+Array of serializable data. Optional — not needed for most use cases.
+
+### mutationFn (required)
+
+Async function called when `runMutation()` is invoked. The argument is whatever you pass to `runMutation()` — an object, a single value, or nothing (`void`).
+
+```tsx
+mutationFn: async (arg) => (await this.api?.deleteJob(arg.id))?.data,
+```
+
+### invalidatedQueries
+
+Array of query keys to invalidate (refetch) after a successful mutation. Using the first key in the array as a namespace will invalidate all queries starting with that key.
+
+```tsx
+invalidatedQueries: [
+    ['myapp', 'tasks'],         // invalidates queries with these first two keys
+    ['myapp', 'progress-tracker'],
+    ['myapp'],                  // invalidates ALL queries under 'myapp'
+],
+```
+
+### onSuccess / onError
+
+Callbacks after the mutation completes. `onSuccess` receives the return value of `mutationFn`. `onError` receives the error object. These can be set both in the mutation options and in `runMutation()` — both will run.
+
+### retry
+
+Number of retry attempts. Default: **0** (no retries for mutations, unlike queries).
+
+See all options at [TanStack Query useMutation reference](https://tanstack.com/query/v5/docs/framework/react/reference/useMutation).
+
+## Integration-Specific Options
+
+| Option | Description |
+|--------|-------------|
+| `invalidatedQueries` | Query keys to refetch after successful mutation |
+| `globalClient` | Use a shared page or app-level client (see [Shared Clients](./04-shared-clients)) |
+
+## Mutation State
+
+Each mutation exposes observable state:
+
+| Flag | When `true` |
+|------|-------------|
+| `isPending` | Mutation is in flight |
+| `isSuccess` | Mutation completed successfully |
+| `isError` | Mutation failed (after retries) |
+
+## Calling Mutations
+
+Use `runMutation()` to execute. The argument matches the `mutationFn` parameter type:
+
+```tsx
+// Object argument
+await store.snooze.runMutation({ id: 42, note: 'Check back later' });
+
+// With inline callbacks
+await store.deleteJob.runMutation(
+    { id: 123 },
+    {
+        onSuccess: () => console.log('Deleted'),
+        onError: (error) => console.error('Failed', error),
+    }
+);
+```
+
+## Runtime Mutations
+
+For mutations created after initialization, use `setupRuntimeMutations()`:
+
+```tsx
+import { setupRuntimeMutations } from '@servicetitan/tanstack-query-mobx/composable';
+
+@queryStore
+class ActionsStore extends Store {
+    private mutations = setupRuntimeMutations();
+
+    setupDelete(entityId: number) {
+        return this.mutations.add<void, { id: number }>(() => ({
+            mutationFn: (args) => this.api?.delete(entityId, args),
+        }), ['delete', entityId]);
+    }
+}
+```

package/docs/tanstack-query-mobx/03-extending-stores.mdx

@@ -0,0 +1,140 @@
+---
+title: Extending Stores
+---
+
+# Extending Stores
+
+## Composable — Shared Factory Functions
+
+Share query definitions across stores with factory functions. Pass a function that returns the observables and services the query needs — MobX tracks them reactively:
+
+```tsx
+// shared/queries/jobs-queries.ts
+export const jobsQuery = (
+    deps: () => { api?: JobsApi; teamId: number } & Partial<QueryApiOptions<Job[]>>
+) => query<Job[]>(() => {
+    const { api, teamId, ...overrides } = deps();
+    return {
+        queryKey: ['scheduling', 'jobs', teamId],
+        queryFn: async () => (await api?.getJobs(teamId))?.data ?? [],
+        enabled: teamId > 0,
+        ...overrides,
+    };
+});
+
+// Different stores reuse the same definition
+@queryStore
+class SchedulingStore extends Store {
+    @inject(JobsApi) private api?: JobsApi;
+    @observable teamId = 0;
+
+    jobs = jobsQuery(() => ({ api: this.api, teamId: this.teamId }));
+}
+
+// Consumer with reactive overrides — MobX tracks everything inside the function
+@queryStore
+class DashboardStore extends Store {
+    @inject(JobsApi) private api?: JobsApi;
+    @observable teamId = 1;
+    @observable hasPermission = false;
+
+    jobs = jobsQuery(() => ({
+        api: this.api,
+        teamId: this.teamId,
+        enabled: this.teamId > 0 && this.hasPermission,
+    }));
+}
+```
+
+## Composable — Getter Override Pattern
+
+Use a `@computed` getter on the base class, override in subclasses:
+
+```tsx
+@queryStore
+class JobsStore extends Store {
+    @inject(JobsApi) protected api?: JobsApi;
+
+    constructor() {
+        super();
+        makeObservable(this);
+    }
+
+    jobs = query<Job[]>(() => this.jobsOptions);
+
+    @computed
+    get jobsOptions(): QueryApiOptions<Job[]> {
+        return {
+            queryKey: ['scheduling', 'jobs'],
+            queryFn: async () => (await this.api?.getJobs())?.data ?? [],
+        };
+    }
+}
+
+// Override the getter — @override replaces @computed in subclass
+@queryStore
+class FilteredJobsStore extends JobsStore {
+    @observable filters = {};
+
+    @override
+    get jobsOptions(): QueryApiOptions<Job[]> {
+        return {
+            ...super.jobsOptions,
+            queryKey: ['scheduling', 'jobs', this.filters],
+        };
+    }
+}
+```
+
+## Inheritance — Extending QueryApiStore
+
+Create a base store with default options, then extend and override:
+
+```tsx
+@injectable()
+class JobsStore extends QueryApiStore<Job[]> {
+    @inject(JobsApi) protected api?: JobsApi;
+
+    get queryOptions(): QueryApiOptions<Job[]> {
+        return {
+            queryKey: ['scheduling', 'jobs'],
+            queryFn: async () => (await this.api?.getJobs())?.data ?? [],
+        };
+    }
+}
+
+// Override — spread super, tweak what you need
+@injectable()
+class FilteredJobsStore extends JobsStore {
+    @observable teamId = 0;
+
+    get queryOptions(): QueryApiOptions<Job[]> {
+        return {
+            ...super.queryOptions,
+            queryKey: ['scheduling', 'jobs', this.teamId],
+            enabled: this.teamId > 0,
+        };
+    }
+}
+```
+
+## Refresh on Mount
+
+When navigating between components, you may want to ensure that data from **other** stores is fresh when a store mounts.
+
+Use the `refreshOnMount()` factory as a class field. The `@queryStore` decorator executes it automatically during `initialize()`:
+
+```tsx
+import { refreshOnMount } from '@servicetitan/tanstack-query-mobx/composable';
+
+@queryStore
+class JobsStore extends Store {
+    jobs = query<Job[]>(() => ({ ... }));
+
+    // Ensure fresh data from external store caches when this store mounts
+    refresh = refreshOnMount(['business-units', 'list'], ['techs', 'list']);
+}
+```
+
+Accepts any number of `QueryKey` arrays and `QueryApi` instances, comma-separated.
+

package/docs/tanstack-query-mobx/04-shared-clients.mdx

@@ -0,0 +1,63 @@
+---
+title: Shared Clients
+---
+
+# Shared Query Clients
+
+To sync and share cached data across multiple Micro Frontends (MFEs), a shared query client can be used at the **page** or **app** level.
+
+## Page-Level Client
+
+Reference-counted — disposes when the last consumer unmounts. Two ways to set up:
+
+### Top-level provider (preferred)
+
+Propagates to all stores underneath:
+
+```tsx
+import { getQueryClient } from '@servicetitan/tanstack-query-mobx/composable';
+
+export const App: FC = provide({
+    singletons: [getQueryClient('page')],
+})(observer(() => <YourApp />));
+```
+
+Multiple MFEs on the same page share a single page client. The library tracks how many consumers are using it across all MFEs — when the last one unmounts, the page client is cleaned up automatically.
+
+### Per-query option
+
+Set `globalClient: 'page'` on an individual query:
+
+```tsx
+// Composable
+jobs = query<Job[]>(() => ({
+    queryKey: ['scheduling', 'jobs'],
+    queryFn: () => this.api?.getJobs(),
+    globalClient: 'page',
+}));
+
+// Inheritance
+get queryOptions(): QueryApiOptions<Job[]> {
+    return {
+        queryKey: ['scheduling', 'jobs'],
+        queryFn: () => this.api?.getJobs(),
+        globalClient: 'page',
+    };
+}
+```
+
+## App-Level Client
+
+Persists until the browser is refreshed or closed. Use cautiously — cached data stays active across all navigation.
+
+Set `globalClient: 'app'` on an individual query:
+
+```tsx
+jobs = query<Job[]>(() => ({
+    queryKey: ['scheduling', 'jobs'],
+    queryFn: () => this.api?.getJobs(),
+    globalClient: 'app',
+}));
+```
+
+Unlike the page client, there is no `getQueryClient('app')` provider. App-level sharing is set per-query using the `globalClient` option.

package/docs/tanstack-query-mobx/05-query-client-store.mdx

@@ -0,0 +1,156 @@
+---
+title: QueryClientStore
+---
+
+# QueryClientStore
+
+The `QueryClientStore` manages the underlying TanStack `QueryClient` instance. The `@queryStore` decorator automatically injects it and wires it into every `QueryApi` and `MutationApi` instance, so most stores don't need to reference it directly.
+
+Use it when you need to manipulate the query cache outside of a specific query — invalidating keys, fetching data imperatively, or cancelling requests.
+
+## Setup
+
+Register it in your provider via `getQueryClient()`:
+
+```tsx
+import { getQueryClient } from '@servicetitan/tanstack-query-mobx/composable';
+
+export const App: FC = provide({
+    singletons: [getQueryClient()],
+})(observer(() => <YourApp />));
+```
+
+To override the defaults, pass a `QueryClientConfig` object:
+
+```tsx
+import { getQueryClient } from '@servicetitan/tanstack-query-mobx/composable';
+
+export const App: FC = provide({
+    singletons: [
+        getQueryClient({
+            defaultOptions: {
+                queries: { staleTime: 5 * 60 * 1000, retry: 1 },
+            },
+        }),
+    ],
+})(observer(() => <YourApp />));
+```
+
+Custom config is only supported for local (component-scoped) clients. Shared clients (`'page'`, `'app'`) use consistent defaults across all MFEs — see [Shared Clients](./04-shared-clients).
+
+## Defaults
+
+The `QueryClientStore` creates a `QueryClient` with these defaults:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `staleTime` | 10 minutes | How long data is considered fresh before refetch |
+| `refetchOnWindowFocus` | `false` | No automatic refetch when the browser tab regains focus |
+| `refetchOnReconnect` | `false` | No automatic refetch when the network reconnects |
+| `retry` | `3` | Number of retry attempts with exponential backoff |
+| `gcTime` | 5 minutes (TanStack default) | Time before inactive queries are garbage collected |
+
+## API
+
+All key-based methods (`invalidate`, `cancel`, `remove`) use **prefix matching** — `['scheduling']` matches all queries starting with that key, like `['scheduling', 'jobs']` and `['scheduling', 'stats']`. This is TanStack Query's default behavior.
+
+### invalidate(keys, options?)
+
+Invalidates queries across **all** available clients (local, page, and app). Invalidated queries are marked stale and refetch automatically when an observer is subscribed.
+
+```tsx
+// Single key
+queryClientStore.invalidate(['scheduling', 'jobs']);
+
+// Multiple keys
+queryClientStore.invalidate([['scheduling', 'jobs'], ['scheduling', 'stats']]);
+
+// With deduplication — skip if currently in an invalidated state
+queryClientStore.invalidate(['scheduling', 'jobs'], { dedupe: true });
+
+// With a different invalidation key (invalidate a broader prefix)
+queryClientStore.invalidate(['scheduling', 'jobs', 42], {
+    invalidationKey: ['scheduling', 'jobs'],
+});
+```
+
+**Options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `dedupe` | `boolean` | Skip if the query is currently in an invalidated state (hasn't refetched yet) |
+| `invalidationKey` | `QueryKey` | Use a different key for invalidation than the one provided |
+
+### fetchQuery(queryConfig, options?)
+
+Fetches a query imperatively without subscribing to it. Respects caching and `staleTime` — if fresh data is already cached, it returns that instead of making a network request. Returns a deep clone of the data.
+
+The query will retry according to the client's retry settings (default: 3 attempts with exponential backoff) before throwing. **Wrap calls in try/catch** — errors are thrown, not swallowed.
+
+```tsx
+try {
+    const report = await queryClientStore.fetchQuery({
+        queryKey: ['reporting', 'report', reportId],
+        queryFn: async () => (await api.getReport(reportId)).data,
+    });
+} catch (error) {
+    // Called after all retries are exhausted
+    console.error('Failed to fetch report:', error);
+}
+```
+
+**Useful query config options (first parameter):**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `staleTime` | `number` | Override stale time for this fetch. Set to `0` to force a fresh network request even if cached data exists |
+| `retry` | `number \| boolean` | Override retry count for this specific fetch |
+| `gcTime` | `number` | Override garbage collection time for this query |
+
+**Second parameter options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `appClient` | `boolean` | Fetch from the app-level shared client instead of the current `QueryClientStore` instance |
+
+### cancel(keys, options?)
+
+Cancels in-flight requests for queries matching the provided key(s).
+
+```tsx
+queryClientStore.cancel(['scheduling', 'jobs']);
+```
+
+**Second parameter options:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `appClient` | `boolean` | Cancel on the app-level shared client instead of the current `QueryClientStore` instance |
+
+### remove(keys)
+
+Removes queries from the cache entirely — the query, its data, and all metadata are deleted. Unlike `invalidate`, this does **not** trigger a refetch.
+
+```tsx
+queryClientStore.remove(['old', 'data']);
+```
+
+### queryClient
+
+This offers direct access to the underlying TanStack `QueryClient` instance. Use it for advanced TanStack Query options not exposed by the methods above — for example, exact key matching:
+
+```tsx
+// Invalidate only ['scheduling', 'jobs', 42], not ['scheduling', 'jobs', 43]
+queryClientStore.queryClient.invalidateQueries({
+    queryKey: ['scheduling', 'jobs', 42],
+    exact: true,
+});
+```
+
+## When to Use Directly
+
+Most stores don't need to inject `QueryClientStore` — each query instance already has its own `invalidate()` method (e.g., `this.jobs.invalidate()`), and the `@queryStore` decorator handles setup and disposal automatically. Inject `QueryClientStore` directly when you need to:
+
+- **Invalidate from outside a query** — e.g., a mutation in one store needs to invalidate a query owned by a different store, using a shared key prefix
+- **Fetch data imperatively** — one-off fetch without setting up a full query subscription
+- **Cancel or remove queries** — clean up specific cache entries on demand

package/docs/tanstack-query-mobx/06-testing.mdx

@@ -0,0 +1,75 @@
+---
+title: Testing
+---
+
+# Testing
+
+Use `ContainerBuilder` from `@servicetitan/tanstack-query-mobx/test` to set up stores in tests. It handles `QueryClientStore` setup, store initialization, and waits for all queries to settle.
+
+## Quick Example
+
+```tsx
+import { ContainerBuilder } from '@servicetitan/tanstack-query-mobx/test';
+
+const { container, initialize } = new ContainerBuilder()
+    .add(JobsStore)
+    .add(JobsApi)
+    .build();
+
+jest.spyOn(container.get(JobsApi), 'getJobs').mockResolvedValue({
+    data: [{ id: 1, title: 'Plumbing' }],
+});
+
+await initialize();
+expect(container.get(JobsStore).jobs.data).toHaveLength(1);
+```
+
+## Test Defaults
+
+`ContainerBuilder` creates a `QueryClientStore` with test-friendly defaults:
+- **`staleTime: Infinity`** — queries never go stale, refetches only on explicit invalidation
+- **`retry: false`** — failed queries don't retry, test failures surface immediately
+
+## Key Features
+
+- **Disabled query detection** — `initialize()` won't hang on queries with `enabled: false`
+- **`skipQueries` option** — skip waiting for specific queries: `await initialize({ skipQueries: [store.details] })`
+- **`ignoreStores` option** — skip entire stores: `await initialize({ ignoreStores: [OtherStore] })`
+- **Mock values** — `builder.add(JobsApi, { useValue: mockApi })` for mock dependencies
+- **`waitFor` helper** — wait for MobX observable conditions: `await waitFor(() => store.items.initialized)`
+
+## Stores with Global Clients
+
+Queries using `globalClient` create shared instances on `window`, which breaks test isolation. Use `useClass` to swap in a local version that strips `globalClient`, or `useValue` to mock the store entirely:
+
+```tsx
+// useClass — keeps real store logic, removes global client
+@queryStore
+class JobsLocalStore extends JobsStore {
+    @override
+    get jobsOptions(): QueryApiOptions<Job[]> {
+        return { ...super.jobsOptions, globalClient: undefined };
+    }
+}
+
+const { initialize } = new ContainerBuilder()
+    .add(JobsStore, { useClass: JobsLocalStore })
+    .build();
+```
+
+```tsx
+// useValue — mock the store shape directly
+const { initialize } = new ContainerBuilder()
+    .add(JobsStore, { useValue: { jobs: { data: mockJobs } } })
+    .build();
+```
+
+## Full Testing Guide
+
+See the complete [Testing Guide](https://github.com/servicetitan/anvil-uikit-contrib/blob/master/packages/tanstack-query-mobx/src/test/TESTING.md) for:
+- `ContainerBuilder` full API
+- Skipping queries and disabled query handling
+- Queries dependent on external data
+- Mock values and `useClass` / `useValue` patterns
+- Manual setup without `ContainerBuilder`
+- Stores with global clients

package/docs/{tanstack-query-mobx.mdx → tanstack-query-mobx/07-examples.mdx}

@@ -1,5 +1,5 @@
 ---
-title: TanStack Query MobX Integration
+title: Examples
 ---
 
 import {
@@ -8,36 +8,32 @@ import {
 
 import { CodeDemo } from '@site/src/components/code-demo';
 
-`@servicetitan/tanstack-query-mobx` contains integrations for using TanStack Query inside MobX stores.
+# Interactive Examples
 
-Documentation for setup and use can be seen [here](https://docs.google.com/document/d/1MfFMtwF4Rb3rj076GWJSgNiA9PtfVThlZBNK4frZHrs/edit?usp=drive_link)
-
-## Examples
-
-### App QueryClient
+## App QueryClient
 
 <CodeDemo example={AppExample} srcPath="tanstack-query-mobx/src/demo/app-example.tsx" />
 
-### Page QueryClient
+## Page QueryClient
 
 <CodeDemo example={PageExample} srcPath="tanstack-query-mobx/src/demo/page-example.tsx" />
 
-### Initial Data
+## Initial Data
 
-#### No Initial Data
+### No Initial Data
 
 <CodeDemo example={NoInitialDataExample} srcPath="tanstack-query-mobx/src/demo/no-initial-data-example.tsx" />
 
-#### Has Initial Data
+### Has Initial Data
 
 <CodeDemo example={HasInitialDataExample} srcPath="tanstack-query-mobx/src/demo/has-initial-data-example.tsx" />
 
-### Stale Time
+## Stale Time
 
-#### Stale Time: 0
+### Stale Time: 0
 
 <CodeDemo example={StaleTime0Example} srcPath="tanstack-query-mobx/src/demo/stale-time-0-example.tsx" />
 
-#### Stale Time: 10 Minutes
+### Stale Time: 10 Minutes
 
 <CodeDemo example={StaleTime10MinutesExample} srcPath="tanstack-query-mobx/src/demo/stale-time-10-minutes-example.tsx" />

package/docs/tanstack-query-mobx/index.mdx

@@ -0,0 +1,119 @@
+---
+title: TanStack Query MobX
+---
+
+# TanStack Query MobX Integration
+
+`@servicetitan/tanstack-query-mobx` integrates [TanStack Query](https://tanstack.com/query/latest) with MobX stores and `@servicetitan/react-ioc` dependency injection. It provides declarative data fetching, caching, automatic query deduplication, and observable state management.
+
+TanStack Query does not provide a query mechanism — you supply an async function using fetch, Axios, or the generated API functions. TanStack Query handles caching, retries, deduplication, refetching, and state.
+
+## Installation
+
+```bash
+npm install @servicetitan/tanstack-query-mobx
+```
+
+## Quick Start
+
+### 1. Provide the Query Client
+
+A `QueryClientStore` is required at the top store level. It creates the TanStack `QueryClient` with sensible defaults (10-minute stale time, 3 retries, no refetch on window focus).
+
+```tsx
+import { getQueryClient } from '@servicetitan/tanstack-query-mobx/composable';
+
+export const App: FC = provide({
+    singletons: [getQueryClient()],
+})(observer(() => <YourApp />));
+```
+
+### 2. Create a Store
+
+Two approaches — both use the same query client.
+
+#### Composable with `@queryStore` (recommended)
+
+The `@queryStore` decorator + `query()`/`mutation()` factories. All queries are class fields with consistent access patterns. Favors composition over inheritance.
+
+```tsx
+import { queryStore, query, mutation } from '@servicetitan/tanstack-query-mobx/composable';
+
+@queryStore
+class JobsStore extends Store {
+    @inject(JobsApi) private api?: JobsApi;
+    @observable selectedJobId = 0;
+
+    jobs = query<Job[]>(() => ({
+        queryKey: ['scheduling', 'jobs'],
+        queryFn: async () => (await this.api?.getJobs())?.data ?? [],
+    }));
+
+    jobDetails = query<JobDetails>(() => ({
+        queryKey: ['scheduling', 'job', this.selectedJobId],
+        queryFn: async () => (await this.api?.getJob(this.selectedJobId))?.data,
+        enabled: this.selectedJobId > 0,
+    }));
+
+    deleteJob = mutation<void, { id: number }>(() => ({
+        mutationFn: async (arg) => await this.api?.deleteJob(arg.id),
+        invalidatedQueries: [['scheduling', 'jobs']],
+    }));
+}
+```
+
+**Why `extends Store`?** Stores must extend `Store` from `@servicetitan/react-ioc` to hook into the react-ioc lifecycle — `initialize()` runs when the provider mounts, `dispose()` runs when it unmounts. The `@queryStore` decorator uses these hooks to auto-wire queries and clean up subscriptions.
+
+**What `@queryStore` handles automatically:**
+- Applies `@injectable()` (no separate decorator needed)
+- Injects `QueryClientStore` (no `@inject(QueryClientStore)` needed)
+- Auto-discovers `QueryApi` and `MutationApi` properties and wires `setup()`/`dispose()`
+- Chains consumer `initialize()` and `dispose()` methods
+- Safe with deep inheritance — prevents double setup/dispose
+
+#### Inheritance with `QueryApiStore`
+
+Extend `QueryApiStore<T>` with a primary query via `queryOptions` getter, plus optional secondary queries via `addQuery()`.
+
+```tsx
+import { QueryApiStore, QueryApiOptions } from '@servicetitan/tanstack-query-mobx';
+
+@injectable()
+class JobsStore extends QueryApiStore<Job[]> {
+    @inject(JobsApi) private api?: JobsApi;
+
+    get queryOptions(): QueryApiOptions<Job[]> {
+        return {
+            queryKey: ['scheduling', 'jobs'],
+            queryFn: async () => (await this.api?.getJobs())?.data ?? [],
+        };
+    }
+
+    deleteJob = this.addMutation<void, { id: number }>(() => ({
+        mutationFn: async (arg) => await this.api?.deleteJob(arg.id),
+        invalidatedQueries: [['scheduling', 'jobs']],
+    }));
+}
+```
+
+### 3. Use in Components
+
+```tsx
+const [store] = useDependencies(JobsStore);
+
+// Composable — access via named query
+const { data, isLoading } = store.jobs;
+
+// Inheritance — primary query proxied to store
+const { data, isLoading } = store;
+```
+
+## How It Works
+
+TanStack Query's main engine is the **query client**. Stores subscribe to the client using composite keys. When a store initializes, it subscribes its queries to the client. When it disposes, it unsubscribes.
+
+- **Queries** are data-driven — they run automatically based on their options. The developer doesn't call them directly. Changes to `queryKey` values trigger refetches via MobX reactivity.
+- **Mutations** are called manually via `runMutation()`. They can automatically invalidate (refetch) related queries after success.
+- **Caching** is per query key. Multiple stores with the same key share one cache and one network request (deduplication).
+
+The `QueryClientStore` creates and manages the TanStack `QueryClient`. The `@queryStore` decorator (or `QueryApiStore` base class) subscribes queries to this client during the react-ioc `initialize()` lifecycle and unsubscribes during `dispose()`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-anvil-uikit-contrib",
-    "version": "38.7.0",
+    "version": "39.0.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "294a6fa2cafd00b82d6a7e0f5f9bea6acab9b2b6"
+    "gitHead": "16cf24bc08b7dde828c65180aa53d7a2b33a33d9"
 }