@imfusion/web-ui 0.5.1-dev.40.gfb5bc73e → 0.5.1-dev.41.g45c10e85

package/package.json

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

package/src/llms/skills/imf-web-ui-conventions/topics/authentication.md

@@ -11,7 +11,7 @@ project-owned — no provider is prescribed or named.
 
 ```text
 src/
-  api/auth/            # getCurrentUser query options, query-key.ts, types.ts, index.ts barrel
+  api/auth/            # getUser query options, keys.ts, types.ts, index.ts barrel
   lib/auth/
     login-url.ts       # pure login navigation helper; not an API topic file
     login-url.test.ts  # focused helper tests
@@ -25,10 +25,10 @@ src/
 
 - One identity source of truth: a server-backed current-user query; never copy session credentials or access tokens into
   React state.
-- The auth topic follows the default [data.md](data.md) shape: `getCurrentUser` in `api/auth/auth.ts`, key leading with the
+- The auth topic follows the default [data.md](data.md) shape: `getUser` in `api/auth/queries.ts`, key leading with the
   `auth` topic, schema in `types.ts`.
 - `lib/auth/login-url.ts`: project-owned navigation helper, not an options factory; tests colocated.
-- Reached as `context.api.auth.getCurrentUser()`; returns query options, never a hook or a user value — callers pick
+- Reached as `context.api.auth.getUser()`; returns query options, never a hook or a user value — callers pick
   `ensureQueryData` or a query hook.
 - Never infer authentication from local storage, a decoded token, a route flag, or permission-gated chrome — stale or
   forgeable; the server response and its schema define the current user.

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

@@ -7,9 +7,11 @@ the boundary principles — validate at the edge, errors as values — not this
 
 - One folder per API topic: options factories, key factory, Zod schemas together, so a query key is never spelled out at a
   call site.
-- Default topic shape `<topic>.ts` + `query-key.ts` + `types.ts`; the reference project's GraphQL transport expands to
-  `keys.ts`, `queries.ts`/`queryFns.ts`, `mutations.ts`/`mutationFns.ts`, `index.ts` — GraphQL-specific, not a transport
-  requirement.
+- Name a file for what it holds, never for the topic it sits in — the folder already says that: `keys.ts`, not `<topic>.ts`
+  or `query-key.ts` (it holds mutation keys too).
+- A file appears only when the topic needs it: a topic with only queries has no `mutations.ts`, and vice versa.
+- A GraphQL (or similarly document-based) transport may split `queries.ts`/`mutations.ts` further into
+  `queryFns.ts`/`mutationFns.ts`; that's an elaboration of the same options-vs-mutations split, not its origin.
 - Transport code (base client, error normalisation): `http/` and nowhere else.
 - Topic helpers: `lib/`, framework-free, tested beside themselves (`build-query-string.ts` + its test) — never inside the
   topic folder.
@@ -19,8 +21,13 @@ src/
   api/
     topics.ts        # one topic registry, reused by keys and namespaces
     index.ts         # topic barrels composed as api.<topic>
-    user/            # expanded topic (used in the examples): index.ts barrel, keys.ts, queries.ts, mutations.ts
-    <topic>/         # default shape: <topic>.ts, query-key.ts, types.ts
+    <topic>/
+      index.ts       # barrel: named re-exports of what other modules call
+      keys.ts        # createApiKeys — query and mutation keys
+      queries.ts     # query options factories — present when the topic has queries
+      mutations.ts   # mutation options factories — present when the topic has mutations
+      types.ts       # Zod schemas + z.infer types
+      types.test.ts  # schema cases, when the schema encodes product behaviour
   http/              # transport: client, error normalisation — the only transport-aware place
   lib/               # framework-free helpers shared by API topics and other callers
 ```
@@ -94,6 +101,8 @@ export type API = typeof api;
 - No topic prefix, no `Options` suffix: `context.api.<topic>.<fn>()` carries both.
 - Queries `get*` (`getAll`, `getById`, `getBySlug`, `getDetails`, `getActive`, `getFiltered`); mutations bare verbs
   (`update`, `login`, `addItem`, `deleteAddress`, `setShippingMethod`).
+- Same suffix-free naming applies to the local binding a query or mutation resolves to —
+  [typescript.md](typescript.md#naming).
 
 ```ts
 // api/user/queries.ts — returns options; keys come from the factory
@@ -166,13 +175,13 @@ export const Route = createFileRoute("/user")({
 
 function UserPage() {
   const context = Route.useRouteContext();
-  const { data: user } = useSuspenseQuery(context.api.user.getDetails());
+  const user = useSuspenseQuery(context.api.user.getDetails());
   const updateUser = useMutation(
     context.api.user.update({
       onSuccess: () => context.queryClient.invalidateQueries({ queryKey: context.api.orders.keys.topic })
     })
   );
-  return <input defaultValue={user.name} onBlur={e => updateUser.mutate({ name: e.target.value })} />;
+  return <input defaultValue={user.data.name} onBlur={e => updateUser.mutate({ name: e.target.value })} />;
 }
 ```
 

package/src/llms/skills/imf-web-ui-conventions/topics/react.md

@@ -44,9 +44,9 @@ function UserCard({ name, role, onEdit }: { name: string; role: string; onEdit:
 ```tsx
 // Smart — knows where data comes from, renders the dumb component
 function UserCardContainer({ userId }: { userId: string }) {
-  const { data } = useUserQuery(userId);
+  const user = useUserQuery(userId);
   const openEditor = useEditorNavigation(userId);
-  return <UserCard name={data.name} role={data.role} onEdit={openEditor} />;
+  return <UserCard name={user.data.name} role={user.data.role} onEdit={openEditor} />;
 }
 ```
 
@@ -95,6 +95,8 @@ useEffect(
 );
 ```
 
+- A dependency sourced from a hook or query return: destructure the primitive first — [typescript.md](typescript.md#naming).
+
 ## Reading list
 
 Consult while building; each is the authority for its topic:

package/src/llms/skills/imf-web-ui-conventions/topics/typescript.md

@@ -43,3 +43,31 @@ const activeNames = users.filter(u => u.isActive).map(u => u.name);
 - Booleans read as assertions: `isOpen`, `hasAccess`, `canSubmit`.
 - Handlers: `onX` as props, `handleX` as implementations.
 - Match the vocabulary the product and the API already use — no synonyms for terms the backend named.
+- Keep the object a hook or query returns as a namespace instead of destructuring it, and drop the `Query`/`Mutation` suffix
+  from the local binding — the binding reads as the domain name, and every field access shows where it came from:
+
+```tsx
+const search = Route.useSearch(); // not const { page, filter } = ...
+const user = useSuspenseQuery(context.api.user.getDetails()); // not const { data } = ...
+const updateUser = useMutation(context.api.user.update());
+
+search.page;
+user.data.name;
+updateUser.mutate(values);
+updateUser.isPending;
+```
+
+- Exception: a `useEffect` dependency array needs a stable primitive, since deps compare by identity — destructure the
+  primitive out first rather than listing the object or a deep path into it:
+
+```tsx
+const user = useSuspenseQuery(context.api.auth.getUser());
+const { name } = user.data; // destructure for the dep array
+
+useEffect(
+  function syncDocumentTitle() {
+    document.title = name;
+  },
+  [name]
+);
+```