@imfusion/web-ui 0.10.1-dev.2.gb6347f49 → 0.10.1-dev.6.gf715361a

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [Unreleased]
+
+### Changed
+
+- Agent skills — Nikolaus Brunner <brunner@imfusion.com>
+  - `imf-web-ui-conventions` has query factories own a numeric `staleTime` chosen by how fast other people change the data.
+    Loaders call `queryClient.query(options)` without an override, and `"static"` no longer appears in factories or
+    `defaultOptions`, where it blocked invalidation refetches.
+  - `imf-web-ui-conventions` puts a route's own views, forms, hooks, and tests in a `-<file-name>/` folder beside the route
+    file, and reserves `partials/` for parts that more than one route uses.
+
+---
+
 ## `0.10.0` &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2026.10.15
 
 ### Highlights
@@ -234,6 +247,37 @@ AppShell sections draw no dividers. Delete overrides of the border properties, w
 - --imf-ui-appshell-border-width: var(--imf-ui-border-size-2);
 ```
 
+Navbar sections pad themselves with `--imf-ui-appshell-navbar-padding`, and that rule outranks a single class. Delete your
+own section padding, and set the variable when the gutter needs to change:
+
+```diff
+- .navSection { padding: 0 var(--imf-ui-appshell-padding); }
++ .root { --imf-ui-appshell-navbar-padding: var(--imf-ui-size-5); }
+```
+
+Nav links widen past the gutter only as `AppShell.NavItem`. Replace hand-built navbar links, and pass a router link through
+`render`:
+
+```diff
+- <MyNavLink to="/products" icon={Box} label="Products" />
++ <AppShell.NavItem render={<Link to="/products" />} icon={<Icon glyph={Box} />}>Products</AppShell.NavItem>
+```
+
+Above `lg` the aside docks whether or not `open` is set. Render no aside when there is nothing to show, not an empty one:
+
+```diff
+- <AppShell.Aside>{selected ? <Details /> : <div />}</AppShell.Aside>
++ {selected ? <AppShell.Aside><Details /></AppShell.Aside> : null}
+```
+
+The navbar's first row and Main's offset read the header height while an `AppShell.Header` is rendered, even when CSS hides
+it. Render the header conditionally instead of hiding it or setting the height to `0`:
+
+```diff
+- <AppShell.Header className={styles.hiddenOnDesktop}>…</AppShell.Header>
++ {isDesktop ? null : <AppShell.Header>…</AppShell.Header>}
+```
+
 ### Breaking
 
 - **Breaking:** The library supports Safari 17.5, Chrome 123, and Firefox 120 or newer. — Nikolaus Brunner <brunner@imfusion.com>
@@ -241,6 +285,11 @@ AppShell sections draw no dividers. Delete overrides of the border properties, w
   - The JavaScript build targets the same versions.
 - **Breaking:** AppShell sections draw no dividers, and the `--imf-ui-appshell-border-color`, `--imf-ui-appshell-border-width`, and `--imf-ui-appshell-border-style` properties are removed. ([WEBSDK-243](https://imfusion.atlassian.net/browse/WEBSDK-243)) — Nikolaus Brunner <brunner@imfusion.com>
 - **Breaking:** `AppShell.Main` is the scroll container and the document does not scroll; window scroll listeners, scroll restoration, and `scrollTo` target `AppShell.Main`. ([WEBSDK-243](https://imfusion.atlassian.net/browse/WEBSDK-243)) — Nikolaus Brunner <brunner@imfusion.com>
+- **Breaking:** AppShell owns its navbar and aside layout. ([WEBSDK-243](https://imfusion.atlassian.net/browse/WEBSDK-243)) — Nikolaus Brunner <brunner@imfusion.com>
+  - Navbar sections pad themselves with `--imf-ui-appshell-navbar-padding` through a rule that outranks a single class.
+  - Only `AppShell.NavItem` widens past the navbar gutter.
+  - Above `lg` the aside docks whether or not `open` is set.
+  - The navbar's first row and Main's offset read the header height whenever an `AppShell.Header` is rendered.
 
 ### Added
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.10.1-dev.2.gb6347f49",
+  "version": "0.10.1-dev.6.gf715361a",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "homepage": "https://imfusion.com",

package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md

@@ -30,6 +30,7 @@ sections one to one — change a topic's sections and this file follows in the s
 
 - [ ] Layout
 - [ ] Application boundary
+- [ ] Route-local code
 - [ ] Imports
 
 ## React — `react`

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

@@ -18,9 +18,8 @@ The file layout is in [project-structure.md](project-structure.md).
 Use one server-backed current-user query as the identity source:
 
 - Put it in `api/auth/queries.ts` and define its key and schema with the [data.md](data.md) pattern.
-- Expose query options as `context.api.auth.getUser()`.
-- Call `queryClient.query({ ...options, staleTime: "static" })` in a loader (see [data.md](data.md)) or a query hook in a
-  component.
+- Expose query options as `context.api.auth.getUser()`, with a numeric `staleTime` set in the factory.
+- Call `queryClient.query(options)` in a loader (see [data.md](data.md)) or a query hook in a component.
 - Keep credentials and access tokens out of React state.
 - Do not infer authentication from local storage, decoded tokens, route flags, or permission-gated UI.
 

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

@@ -29,7 +29,8 @@ export function UserCard({ name, onEdit }: UserCardProps) {
 ## Grouping
 
 Group by component role, such as layout or domain UI, according to the project structure. Do not create a hierarchy before
-the project needs one.
+the project needs one. Components that only one route uses go in that route's `-` folder, not a shared group; see
+[project-structure.md](project-structure.md).
 
 ## One file or a folder
 
@@ -50,3 +51,5 @@ The barrel only re-exports the public pieces.
 
 Keep a component's stylesheet, tests, and local types beside the component. A container that needs styling usually wants to
 be a layout or dumb component instead.
+
+A route-local component keeps its stylesheet and tests in the route's `-` folder beside it.

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

@@ -85,11 +85,17 @@ export function getDetails(options?: QueryOptions<User>) {
 }
 ```
 
-Callers choose `queryClient.query`, `useSuspenseQuery`, or another Query API. A router loader reads the cache with
-`queryClient.query({ ...options, staleTime: "static" })`, not the deprecated `ensureQueryData` or `fetchQuery`. Keep
-`"static"`: without it the factory's `staleTime` applies (default 0), so every loader run waits on the network and the page's
-`useQuery` refetches on mount. Mutation factories likewise return `mutationOptions`, own their mutation key and parsing, and
-are passed to `useMutation`; do not inline those options at the call site.
+Callers choose `queryClient.query`, `useSuspenseQuery`, or another Query API. The factory owns `staleTime` as a number,
+chosen by how fast other people change the data: near zero for data others edit often, minutes for data that rarely changes.
+A router loader reads the cache with `queryClient.query(options)` and no override, not the deprecated `ensureQueryData` or
+`fetchQuery`.
+
+Never set `staleTime: "static"` in a factory or in `defaultOptions`. A query whose observers are all static is never
+refetched, so invalidation after a mutation does nothing. Invalidation marks a query stale even when its `staleTime` is a
+number, so the app's own mutations still refresh the data. Changes made by others show once the window expires.
+
+Mutation factories likewise return `mutationOptions`, own their mutation key and parsing, and are passed to `useMutation`; do
+not inline those options at the call site.
 
 ## Router context access
 

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

@@ -29,6 +29,17 @@ Create the root providers, current-user boundary, and pathless `_public/` and `_
 new app starts `_app/` with a minimal `AppShell` unless it has no persistent authenticated navigation. An established app
 keeps its working shell choice.
 
+## Route-local code
+
+A route file holds its search schema and `validateSearch`, its loaders, and its pending, error, and not-found components.
+Route-local code that outgrows small in-file components (views, forms, hooks, tests) goes in a sibling folder named `-` plus
+the route file's name: `route.tsx` gets `-route/`, `products.tsx` gets `-products/`. TanStack Router ignores files and
+folders with a leading `-` when it builds the route tree, so the folder never becomes a route. The folder holds the route's
+views with their props types, hooks, `.module.css` files, and tests. A component small enough to sit in the route file stays
+there.
+
+`partials/` holds only parts that more than one route uses.
+
 ## Imports
 
 Use `./` for siblings and `#/` for imports elsewhere in `src/`:

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

@@ -5,10 +5,12 @@ looks.
 
 ## Composition: pages (smart containers), partials, dumb components
 
-- **Pages** live in `routes/`. They load data, read URL state, coordinate actions, and compose the view. They do not own
-  component CSS.
-- **Partials** are reusable compositions extracted because they read as a unit. They have light logic and no styling of their
-  own.
+- **Pages** live in `routes/`. They load data, read URL state, coordinate actions, and compose the view. Route files hold the
+  search schema, loaders, and pending, error, and not-found components. They do not own component CSS. Route-local views and
+  forms live in the route's `-` folder, as [project-structure.md](project-structure.md) describes, and that folder's
+  `.module.css` files are component styles.
+- **Partials** are compositions that more than one route uses, extracted because they read as a unit. They have light logic
+  and no styling of their own.
 - **Layout components** arrange content with `Stack`, `Row`, grids, and token gaps, and wrap long-form text in `Prose`.
 - **Dumb components** receive data and callbacks, render UI, and own their styles. They do not fetch, route, or contain
   business rules.