@imfusion/web-ui 0.5.1-dev.56.gcf89961f → 0.5.1-dev.6.g9d275fa8

package/src/llms/llms.gen.txt

@@ -73,23 +73,6 @@ Off-canvas panel that slides in from a screen edge. Use for mobile navigation, s
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .drawer (jq: jq '.drawer' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/drawer.md
 
-## Field
-- category: Inputs, status: stable
-Accessible field composition for a label, form control, supporting description, and inline validation message. Use it to associate a control such as Input, Checkbox, or Select with field state including valid, invalid, dirty, touched, filled, and focused.
-- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .field (jq: jq '.field' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
-- further reading (usage/anatomy, not props): https://base-ui.com/react/components/field.md
-
-## Fieldset
-- category: Inputs, status: stable
-Semantic grouping for related form controls with a shared legend. Also called a form group; use it to communicate a common topic and propagate disabled state without introducing a decorative container.
-- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .fieldset (jq: jq '.fieldset' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
-- further reading (usage/anatomy, not props): https://base-ui.com/react/components/fieldset.md
-
-## Icon
-- category: Display, status: stable
-Semantic color wrapper for an icon imported from the Web UI icons entry. Use it when an icon needs a named foreground role instead of the inherited currentColor.
-- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .icon (jq: jq '.icon' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
-
 ## ImageDisplayOptions
 - category: Inputs, status: experimental
 A panel or toolbar of controls bound to an image dataset's display options.

package/src/llms/skills/imf-web-ui/SKILL.md

@@ -2,8 +2,8 @@
 name: imf-web-ui
 description:
   "Entry point for UI work in a project that depends on @imfusion/web-ui. Decides whether guidance is needed at all, then
-  routes to the right companion skill — component reference, UX guidance, or frontend conventions. Load when adding or
-  editing UI in a consumer repo."
+  routes to the right companion skill — component reference, UX guidance, or frontend patterns. Load when adding or editing
+  UI in a consumer repo."
 ---
 
 # imf-web-ui
@@ -24,17 +24,16 @@ Guidance skills exist to fill gaps, not to add ceremony to clear tasks.
 
 ## Routing
 
-| The task at hand                                                                                      | Open                                    |
-| ----------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| Using a specific component; checking props, sub-components, or defaults                               | `imf-web-ui-components`                 |
-| First-time setup, adding a library dependency, or components rendering unstyled/broken                | `imf-web-ui-setup` (`library-setup`)    |
-| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states  | `imf-web-ui-ux`                         |
-| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing     | `imf-web-ui-conventions`                |
-| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-setup` / `imf-web-ui-audit` |
-| Installing or checking agent tooling: vendored skills, lifecycle hooks, registrations, and staleness  | `imf-web-ui-setup` / `imf-web-ui-audit` |
-
-The two setup rows are narrow on purpose. They're for "what is this project missing?" — a question about the repo as a whole.
-Being asked to add one config file is just that edit; make it, and don't open a skill to do so.
+| The task at hand                                                                                      | Open                                 |
+| ----------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| Using a specific component; checking props, sub-components, or defaults                               | `imf-web-ui-components`              |
+| First-time setup, adding a library dependency, or components rendering unstyled/broken                | `imf-web-ui-setup`                   |
+| Building/reshaping a screen or flow; choosing between components; layout, density, hierarchy, states  | `imf-web-ui-ux`                      |
+| Writing wrappers or custom UI; styling beyond defaults; adding files; TypeScript, naming, testing     | `imf-web-ui-frontend-patterns`       |
+| Setting up or auditing an **ImFusion** repo's tooling: formatting, linting, hooks, scripts, structure | `imf-web-ui-imfusion-frontend-setup` |
+
+The last row is narrow on purpose. It's for "what is this project missing?" — a question about the repo as a whole. Being
+asked to add one config file is just that edit; make it, and don't open a skill to do so.
 
 Tasks routinely span two: building a screen usually means `imf-web-ui-ux` for the shape and `imf-web-ui-components` for the
 APIs. That's normal — open both, in that order.

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

@@ -1,10 +1,9 @@
 ---
 name: imf-web-ui-components
 description:
-  "Look up @imfusion/web-ui component APIs and icon glyphs without reading source. Load when you need a component's props,
-  sub-components, defaults, or a supplied icon — not for choosing between components (imf-web-ui-ux) or first-time setup
-  (imf-web-ui-setup library-setup)."
-allowed-tools: Bash
+  "Look up @imfusion/web-ui component APIs without reading their source: the two-hop lookup (identity index -> prop data),
+  compound components, and integrations. Load when you need the props, sub-components, or defaults of a specific component —
+  not for choosing between components (imf-web-ui-ux) or first-time setup (imf-web-ui-setup)."
 ---
 
 # imf-web-ui-components
@@ -16,8 +15,6 @@ reading source or checking out the library's repo:
   and a one-sentence description of what it's for and what else it's called.
 - **`node_modules/@imfusion/web-ui/src/docgen/doc.gen.json`** — full prop tables (name, type, default, description) for every
   component, keyed by kebab-case folder name.
-- **`node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json`** — searchable icon names, styles, categories, and tags.
-  Read it only when the task needs an icon.
 
 Neither file is reachable through the package's pretty import paths (`@imfusion/web-ui/llms.txt`,
 `@imfusion/web-ui/docgen.json`) — those are Node module-resolution aliases, meaningless to `cat`/`jq`/`grep` reading files
@@ -75,56 +72,6 @@ don't guess at an API — that's a real gap to report, not something to work aro
 maintainer, or file it in the [WEBSDK Jira project](https://imfusion.atlassian.net/browse/WEBSDK) if you have access. If the
 gap is about _which_ component to use rather than a missing one, that's a design question: open `imf-web-ui-ux`.
 
-## Icons
-
-When the task mentions an icon, glyph, symbol, or `@imfusion/web-ui/icons`, query the icon catalog before choosing a name. Do
-not load it for ordinary component work.
-
-Search one relevant term at a time, then read only the matching records:
-
-```sh
-node -e '
-  const q = process.argv[1].toLowerCase();
-  const icons = JSON.parse(
-    require("fs").readFileSync(
-      "node_modules/@imfusion/web-ui/src/llms/icon-catalog.gen.json",
-      "utf8"
-    )
-  );
-  console.log(
-    JSON.stringify(
-      icons
-        .filter(icon => [icon.name, icon.category, ...icon.tags]
-          .join(" ")
-          .toLowerCase()
-          .includes(q))
-        .slice(0, 20),
-      null,
-      2
-    )
-  );
-' "add"
-```
-
-Import the chosen glyph and `Icon` from `@imfusion/web-ui/icons`. Render it through `Icon`, including when it inherits the
-surrounding color:
-
-```tsx
-import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
-
-<Icon glyph={ArrowRight} aria-hidden />;
-```
-
-Use `Icon` for every rendered icon. Pass the component reference, not a rendered element:
-
-```tsx
-import { ArrowRight, Icon } from "@imfusion/web-ui/icons";
-
-<Icon glyph={ArrowRight} size={16} variant="primary" aria-label="Continue" role="img" />;
-```
-
-Never import `iconoir-react` or another icon package directly.
-
 ## Compound components
 
 A component whose docgen entry has a non-empty `subComponents` array is used as a namespace, not a single import — e.g.

package/src/llms/skills/imf-web-ui-frontend-patterns/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: imf-web-ui-frontend-patterns
+description:
+  "Raise the quality of frontend code written around @imfusion/web-ui — including quickly vibe-coded frontends. Library
+  boundary contract (tokens, CSS layers, type derivation), component roles, state placement, effects discipline, code
+  conventions (TypeScript, naming, file organisation, testing), and stack defaults. Load when writing wrapper components,
+  custom UI, styling beyond the defaults, adding new files to a consumer app, or choosing a routing, data-fetching, form, or
+  table library."
+---
+
+# imf-web-ui-frontend-patterns
+
+One guard, once: **if the host project already has a convention — a styling system, a state library, a folder shape — the
+project wins.** These defaults fill vacuums. They are not a license to refactor a consumer codebase toward this document.
+
+Everything else below is how to build.
+
+## Stay behind the library
+
+Never import Base UI (or any other upstream this library wraps) directly — no upstream stylesheets, no upstream components,
+even when upstream docs show it that way. Everything a component needs ships in `@imfusion/web-ui`. If the library is missing
+something upstream has, report the gap (see `imf-web-ui-components`); don't reach around it.
+
+## Style through the sanctioned seams
+
+All library styles live in the `imf-ui.components` CSS layer, so **any plain selector you write wins** — that's the whole
+override contract:
+
+- Target the stable hooks: `data-imf-ui-component` attributes and your own classes/wrappers.
+- Never target the library's internal class names — they are generated and change without notice.
+- Never `!important` — if you think you need it, you're targeting the wrong thing.
+
+## Build custom UI from tokens
+
+Anything you build that the library doesn't cover — a stat widget, a custom panel — uses `--imf-ui-*` variables for color,
+spacing, radius, and type instead of hardcoded values. That's what makes custom UI look native next to library components,
+and what keeps it correct when the theme changes. A hex code or a magic `px` next to a concept the tokens already name is a
+defect.
+
+## Derive types, don't import them
+
+Prop types come from the components themselves: `React.ComponentProps<typeof Button>`. The library deliberately exports no
+`Props` types — don't look for them, and don't re-declare prop shapes by hand.
+
+## Integrations own their peers
+
+Components under `@imfusion/web-ui/integrations/*` depend on optional peers (e.g. `@tanstack/highlight` for `CodeHighlight`).
+Add the peer explicitly to the consumer's `package.json` — never rely on hoisting.
+
+## React patterns
+
+The full treatment — component roles with an example, state placement, effects discipline, and the react.dev sources to
+consult while building — lives in [references/react-patterns.md](references/react-patterns.md). Read it before writing new
+screens or wrappers. The core in one breath:
+
+- **Three roles.** Dumb components own how things look, layout components own arrangement, smart containers own data and
+  logic. Styling never lives in containers.
+- **State lives where its truth lives.** URL → query cache → context → store → local state; walk the list, stop at the first
+  match.
+- **Effects are a last resort**, and always extracted into purpose-named hooks.
+- **Compose, don't configure.** If a component's prop list reads like a settings page, it wanted to be two or three
+  components.
+
+## Everything else about the code
+
+TypeScript, naming, where files go, and what's worth testing live in
+[references/code-conventions.md](references/code-conventions.md). Read it when you're adding files rather than editing
+existing ones — that's when these choices get made and then inherited by everything after.
+
+The split between the two references: `react-patterns.md` covers **writing React** — component roles, where state lives,
+effects discipline, composition. `code-conventions.md` covers **the code around it** — TypeScript, JS style, naming, file
+layout, testing. Starting a new feature usually wants both.
+
+## Stack defaults
+
+TanStack is the default for the tooling around web-ui, whether the app is greenfield or you're adding one screen to something
+that already exists. The ones you'll reach for most: **Router** (URL state, type-safe search params), **Query** (server
+state), **Form** (form state), and **Table** for data grids, which you pair with web-ui's styled `Table` parts
+(`Table.SortableHeaderCell` carries the sort glue). The suite goes wider than those four — check what exists before adding a
+non-TanStack dependency. This is the stack the state ladder assumes.
+
+`useState` is the right tool for local UI state, and most of it is local: whether a panel is open, which tab is active, a
+draft value being typed, a hover flag. Keep those in the component and don't reach for a library.
+
+The line is what the state is _for_, not how much of it there is. A library owns the layer once you find yourself rebuilding
+what it does: validation timing and cross-field rules (**Form**), caching and refetching (**Query**), URL as the source of
+truth (**Router**), sorting and pagination over rows (**Table**). web-ui ships none of that logic, and that absence is not an
+argument for writing it yourself. Adding the library mid-project is normal and cheap; unpicking a hand-rolled version of it
+later is not.
+
+For best practices and patterns within any of these libraries, go to the library's own guidance rather than working from
+memory: `npx @tanstack/cli` for docs. Where a project has wired up `@tanstack/intent`, use it to reach the Agent Skills its
+TanStack dependencies ship, and read those too.

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

@@ -0,0 +1,133 @@
+# Code conventions
+
+The ImFusion defaults for everyday code around `@imfusion/web-ui` — the parts that aren't React-specific. TypeScript, file
+organisation, naming, and testing. React component structure lives in [react-patterns.md](react-patterns.md); the two are
+read together when starting new code.
+
+These fill vacuums. Where the host project has already decided, the project wins.
+
+## TypeScript
+
+- **`any` is forbidden.** `unknown` at a boundary you genuinely can't type, narrowed before use. An `any` that silences an
+  error moves the failure from compile time to runtime, which is the opposite of the trade you wanted.
+- **Lean on inference for locals; annotate the contract.** Restating a type the compiler already knows inside a function body
+  is a second thing to keep in sync. An **explicit return type on an exported function is worth writing**: it's the promise
+  the module makes, it stops an internal refactor silently widening the public shape, and it makes the error surface at the
+  function rather than at every call site.
+- **No temporal coupling.** Don't initialise to `null` and fill the value in later — model the states instead, so "not loaded
+  yet" and "loaded, empty" aren't the same value.
+- **Avoid `as`.** A type assertion tells the compiler to stop checking exactly where checking is worth most. Fix the type.
+  Assertions at an untyped third-party boundary are the honest exception; keep them at the boundary, not spread through call
+  sites.
+
+**Derive types, don't duplicate them.** One source of truth, everything else follows from it:
+
+```ts
+const sizes = ["sm", "md", "lg"] as const;
+type Size = (typeof sizes)[number];
+
+const labels: Record<Size, string> = { sm: "S", md: "M", lg: "L" }; // compiler breaks if `sizes` changes
+```
+
+The same rule crosses the library boundary: prop types come from the components themselves
+(`React.ComponentProps<typeof Button>`), never re-declared by hand.
+
+**Function signatures.** One or two positional arguments read fine. At three or more, take a single object and destructure —
+call sites stop depending on argument order, and adding a parameter stops being a breaking change.
+
+## Expressions over statements
+
+Reach for the array methods before the loop. `map`, `filter`, `find`, `some`, `every`, `flatMap`, `reduce` — each names what
+it's doing, where a `for` loop makes you read the body to find out.
+
+```ts
+// The name is the documentation
+const activeNames = users.filter(u => u.isActive).map(u => u.name);
+
+// vs. a loop you have to read to understand
+const activeNames = [];
+for (const u of users) {
+  if (u.isActive) activeNames.push(u.name);
+}
+```
+
+The deeper reason is mutation: the method chain produces a new value, so nothing else can observe a half-built array. Prefer
+spreads and `structuredClone` over in-place edits, and `toSorted`/`toReversed` over `sort`/`reverse`, which mutate their
+receiver and have surprised everyone at least once.
+
+Two honest exceptions: a genuine early exit (`for` with `break` beats `find` returning a sentinel) and a hot loop over
+thousands of items where the intermediate arrays actually measure. Neither is the common case, so reach for the method first
+and justify the loop.
+
+Keep the chain flat. Three or four steps read well; ten want intermediate named constants, and a `reduce` doing four things
+at once wants to be a loop after all.
+
+## Naming
+
+- Say what it is, not what it is made of. `useUserQuery`, not `useUserHook`. `retryDelay`, not `num`.
+- Booleans read as assertions: `isOpen`, `hasAccess`, `canSubmit`. A boolean called `status` will end up holding a string.
+- Handlers are `onX` as props, `handleX` as implementations — the prop names the event, the function names the response.
+- Match the vocabulary the product and the API already use. Inventing a synonym for a term the backend already named costs a
+  translation step on every read.
+
+## File and folder organisation
+
+Kebab-case throughout, folders and files.
+
+```
+src/
+  routes/          # TanStack Router file-based routes; routing only
+  api/<topic>/     # <topic>.ts (queries/mutations), query-key.ts, types.ts
+  components/      # grouped by kind of component — layouts/, primitives/, or a domain name
+  http/            # client, error normalisation
+  lib/             # framework-free helpers
+```
+
+`api/` groups by topic: a query lives next to its key factory and its types, so a query key is never spelled out at a call
+site. Routes compose and don't fetch inline. Transport concerns live in `http/` and nowhere else.
+
+`components/` groups by kind — a layout component under `layouts/`, not beside a domain widget. Flat is fine while there are
+few; let the grouping follow what the project has rather than imposing it up front. The kinds worth separating are the
+component roles in [react-patterns.md](react-patterns.md): dumb components, layout components, smart containers.
+
+A component gets a folder once it has more than one file, with an `index.ts` that only re-exports:
+
+```
+components/data-table/
+  data-table.tsx
+  data-table-row.tsx
+  data-table.module.css
+  index.ts
+```
+
+Colocate tests, styles, and types with their subject. A file you have to hunt for in a parallel tree gets edited less
+carefully.
+
+## Styling
+
+**CSS Modules by default**, colocated as `<component>.module.css`. No CSS-in-JS, no utility-class framework. Compose from
+`--imf-ui-*` tokens so custom UI stays consistent with library components and follows the theme; the override contract (CSS
+layers, `data-imf-ui-component`, never the library's generated class names) is in the parent skill.
+
+`imf-web-ui-imfusion-frontend-setup` sets up or audits this structure on an ImFusion project.
+
+## Testing
+
+Test the **decisions**, not the rendering.
+
+- **Pure logic gets unit tests** — pricing, permissions, date math, parsing, reducers. These are cheap, fast, and the place
+  bugs actually hide.
+- **Presentational components generally don't.** A component that maps props onto web-ui primitives has no logic of its own;
+  asserting that it rendered a `<Button>` tests React, not your code.
+- **Behaviour a user performs gets an interaction test** — a form that validates, a flow with steps. Test it through the
+  interface the user has (roles, labels, visible text), not through internals.
+- **Extract the decision out of a hook and test that.** A hook whose interesting part is a plain function is easier to test
+  as a plain function than through a render harness. A hook that only wraps a browser API has no decision to extract.
+
+The measure isn't coverage percentage. It's whether a test failing tells you something you didn't already know.
+
+## Formatting and linting
+
+Don't argue about it in review — the tooling decides, and it runs before the commit lands. A formatter, a linter, and a
+pre-commit hook wired so none of them is optional. On an ImFusion project, `imf-web-ui-imfusion-frontend-setup` carries the
+baseline and the setup steps.

package/src/llms/skills/imf-web-ui-frontend-patterns/references/react-patterns.md

@@ -0,0 +1,94 @@
+# React patterns
+
+The house defaults for the React code around `@imfusion/web-ui`, in full. The links throughout are for **you, the agent**:
+consult them while building — they are the authoritative source when a case here is ambiguous. Hand them to the human only if
+asked.
+
+## Component roles
+
+Dumb/smart separation is standard React practice (it traces back to Dan Abramov's
+["Presentational and Container Components"](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0) and
+survives in [Thinking in React](https://react.dev/learn/thinking-in-react)). The house version has three roles:
+
+- **Dumb components** own how things _look_. They style and compose library primitives, receive plain data and callbacks as
+  props, and know nothing about fetching, routing, or business logic. All non-layout styling lives here — and only here.
+- **Layout components** own _arrangement_ — and nothing else. `Stack`- and `Row`-based wrappers with token gaps, a page grid,
+  a section frame. They exist because smart containers are styleless: when a container needs two panels side by side, that
+  arrangement is a layout component, not an inline style.
+- **Smart containers** own how things _work_. Routes (or explicit container components) fetch data, hold orchestration logic,
+  and wire the other two together. Zero styling — the moment a container wants CSS, extract a layout component.
+
+```tsx
+// Dumb — renders what it's given
+function UserCard({ name, role, onEdit }: { name: string; role: string; onEdit: () => void }) {
+  return (
+    <Card.Root>
+      <Card.Content>
+        <Typo>{name}</Typo>
+        <Chip>{role}</Chip>
+      </Card.Content>
+      <Card.Footer>
+        <Button onClick={onEdit}>Edit</Button>
+      </Card.Footer>
+    </Card.Root>
+  );
+}
+
+// Smart — knows where data comes from, renders the dumb component
+function UserCardContainer({ userId }: { userId: string }) {
+  const { data } = useUserQuery(userId);
+  const openEditor = useEditorNavigation(userId);
+  return <UserCard name={data.name} role={data.role} onEdit={openEditor} />;
+}
+```
+
+Why it matters here: dumb components are the layer where `@imfusion/web-ui` lives. Keeping them free of logic keeps every
+screen restylable, testable with plain props, and resilient to library updates. The one web-ui-specific addition: wrap
+`experimental` components (marked in the identity index) in a dumb component once per app even if you add nothing yet — a
+breaking upstream change then lands in one file instead of every call site.
+
+## Compose, don't configure
+
+Build screen-level pieces by composing primitives (`Stack`, `Row`, `Card`, your dumb components) rather than growing one
+component with a dozen boolean props. If a component's prop list reads like a settings page, it wanted to be two or three
+components. When state must be shared between siblings, lift it to the nearest common parent —
+[Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) — rather than syncing copies.
+
+## Put state where its truth lives
+
+Work down this list and stop at the first match:
+
+1. **Shareable via URL?** (filters, sort, pagination, active tab) → router search params. Back button and copied links are UX
+   features you get for free.
+2. **Comes from an API?** → the data-fetching layer's cache (e.g. TanStack Query). Never copy server data into `useState` —
+   that's how stale-UI bugs are born.
+3. **Scoped to a subtree, resets on leave?** (wizard progress) → React context.
+4. **App-wide and persistent?** → a client store, and only now.
+5. **Local to one component?** (input value, open/closed) → `useState`.
+
+Most frontends need far less of tier 4 than they think; tiers 1–2 usually dissolve the "we need a store" instinct. For
+structuring the state itself, [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) is the
+reference — especially its rules on avoiding redundant and duplicated state.
+
+## Effects: last resort, and named
+
+Before writing `useEffect`, check: derived values belong in render (or `useMemo`), responses to user actions belong in the
+event handler, and server synchronization belongs in the data-fetching layer. Effects are for synchronizing with systems
+_outside_ React. The definitive catalog of effect misuses — read it before every effect you're tempted to write — is
+[You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect).
+
+When an effect is genuinely needed, extract it into a custom hook named for its purpose — `useSyncedScroll`,
+`useDocumentTitle`, `useHotkey` — never an anonymous `useEffect` block inline in a component. The name documents intent, the
+hook isolates the dependency array, and the component body stays declarative. Pattern reference:
+[Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks).
+
+## Reading list
+
+Consult while building; each is the authority for its topic:
+
+- [Thinking in React](https://react.dev/learn/thinking-in-react) — decomposition and one-way data flow
+- [Keeping Components Pure](https://react.dev/learn/keeping-components-pure) — why dumb components stay dumb
+- [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure) — shaping state without duplication
+- [Sharing State Between Components](https://react.dev/learn/sharing-state-between-components) — lifting state
+- [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) — the effect misuse catalog
+- [Reusing Logic with Custom Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) — named effects live here