@imfusion/web-ui 0.5.1-dev.17.g60f2cb91 → 0.5.1-dev.19.g11b806f9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.5.1-dev.17.g60f2cb91",
+  "version": "0.5.1-dev.19.g11b806f9",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "license": "UNLICENSED",

package/src/llms/skills/imf-web-ui-frontend-conventions/references/data.md

@@ -12,7 +12,6 @@ src/
     <topic>.ts       #   queryOptions / mutationOptions
     query-key.ts     #   key factory, topic as the first segment
     types.ts         #   Zod schemas + z.infer types
-    use-<thing>.ts   #   hooks wrapping the options for components
   http/              # transport: client, error normalisation — the only transport-aware place
 ```
 
@@ -65,19 +64,8 @@ export const userQueryOptions = () =>
   });
 ```
 
-The hook a component consumes:
-
-```ts
-// api/user/use-user.ts
-import { useSuspenseQuery } from "@tanstack/react-query";
-
-import { userQueryOptions } from "./user";
-
-export const useUser = () => useSuspenseQuery(userQueryOptions());
-```
-
-The options and their hook can start colocated in one file — options right beside the hook that consumes them — and split
-into separate files when the topic's complexity demands it.
+Components consume query options directly with `useSuspenseQuery` (prefetched routes) or `useQuery` (secondary data). No
+wrapper hooks — the options function is the reusable unit.
 
 Mutations follow the same shape with `mutationOptions`, the dirtied topic first in the `mutationKey`:
 
@@ -90,8 +78,86 @@ export const updateUserMutationOptions = () =>
   });
 ```
 
-Routes prefetch in the `loader` with `context.queryClient.ensureQueryData(userQueryOptions())`, components read with the
-`useSuspenseQuery` hook. Give the route a `pendingComponent`; let errors bubble to the nearest `errorComponent`.
+The root route types the router context so every loader can reach the query client via DI:
+
+```ts
+// routes/__root.tsx
+import { Outlet, createRootRouteWithContext } from "@tanstack/react-router";
+import type { QueryClient } from "@tanstack/react-query";
+
+interface RouterContext {
+  queryClient: QueryClient;
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: () => <Outlet />
+});
+```
+
+The router is created with that context filled in:
+
+```ts
+// router.ts
+import { createRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+import { createQueryClient } from "./query-client";
+
+const queryClient = createQueryClient();
+
+export const router = createRouter({
+  routeTree,
+  context: { queryClient }
+});
+```
+
+A route prefetches in the `loader`, reads with `useSuspenseQuery`, and provides a `pendingComponent`; errors bubble to the
+nearest `errorComponent`:
+
+```tsx
+// routes/me.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+import { userQueryOptions } from "#/api/user/user";
+
+export const Route = createFileRoute("/me")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(userQueryOptions()),
+  pendingComponent: () => <p>Loading…</p>,
+  component: MePage
+});
+
+function MePage() {
+  const { data: user } = useSuspenseQuery(userQueryOptions());
+  return <h1>{user.name}</h1>;
+}
+```
+
+Mutations use `useMutation` with the options factory. Manual invalidation is unnecessary when automatic invalidation is on
+(see below):
+
+```tsx
+// components/user-settings.tsx
+import { useMutation } from "@tanstack/react-query";
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+import { userQueryOptions, updateUserMutationOptions } from "#/api/user/user";
+
+function UserSettings() {
+  const { data: user } = useSuspenseQuery(userQueryOptions());
+  const updateUser = useMutation(updateUserMutationOptions());
+
+  return (
+    <form
+      onSubmit={e => {
+        e.preventDefault();
+        updateUser.mutate({ name: "New Name" });
+      }}
+    >
+      <input defaultValue={user.name} />
+    </form>
+  );
+}
+```
 
 ## Automatic invalidation