@imfusion/web-ui 0.10.1-dev.34.gb01a818e → 0.10.1-dev.41.g467e0e1a

package/src/docgen/doc.gen.json

@@ -118,7 +118,7 @@
   "app-shell": {
     "root": {
       "name": "AppShell.Root",
-      "description": "",
+      "description": "AppShell — application layout shell.\n\nThe classic dashboard frame: collapsible navbar/aside sidebars, a page\nheader, an optional footer, and a scrolling main content area. Also called\nan app layout, application frame, dashboard shell, or sidebar layout.\n\nComposed of eight sub-components used with dot-notation: `AppShell.Root` wraps\n`AppShell.Header`, `AppShell.Navbar`, `AppShell.Aside`, `AppShell.Footer`,\n`AppShell.Main`, and (inside a sidebar) `AppShell.Section` and `AppShell.NavItem`.\n\nSizing is CSS-driven — override the `--imf-ui-appshell-*` custom properties\nrather than passing dimension props. Below the responsive breakpoints the\nnavbar (`md`) and aside (`lg`) open as drawers, and the shell renders the\nnavbar's toggle itself.\n\nCopied and adapted from Mantine's AppShell; no upstream runtime dependency.\nMIT licensed (see Mantine repo).",
       "props": [
         {
           "name": "ref",
@@ -141,6 +141,13 @@
             "defaultValue": "Close panel",
             "description": "Accessible name of the close button shown while the aside is a drawer."
           },
+          {
+            "name": "defaultOpen",
+            "required": false,
+            "type": "boolean",
+            "defaultValue": null,
+            "description": "Whether the drawer starts open when `open` is omitted."
+          },
           {
             "name": "onOpenChange",
             "required": false,
@@ -185,68 +192,6 @@
           }
         ]
       },
-      {
-        "name": "AppShell.Burger",
-        "description": "AppShell.Burger — the menu toggle: three sheared bands that cross while the navbar drawer is open. With no props it\nopens and closes that drawer. Takes its color from the surface and hides from `md` up, where the navbar is docked, and\nsteps back while the drawer is open, so the drawer's own close is the only one shown.",
-        "props": [
-          {
-            "name": "className",
-            "required": false,
-            "type": "string | ((state: ButtonState) => string)",
-            "defaultValue": null,
-            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component's state."
-          },
-          {
-            "name": "focusableWhenDisabled",
-            "required": false,
-            "type": "boolean",
-            "defaultValue": "false",
-            "description": "Whether the button should be focusable when disabled."
-          },
-          {
-            "name": "label",
-            "required": false,
-            "type": "string",
-            "defaultValue": null,
-            "description": "Accessible name. Defaults to \"Open navigation\" or \"Close navigation\" from `opened`."
-          },
-          {
-            "name": "nativeButton",
-            "required": false,
-            "type": "boolean",
-            "defaultValue": "true",
-            "description": "Whether the component renders a native `<button>` element when replacing it\nvia the `render` prop.\nSet to `false` if the rendered element is not a button (for example, `<div>`)."
-          },
-          {
-            "name": "opened",
-            "required": false,
-            "type": "boolean",
-            "defaultValue": null,
-            "description": "Draws the cross and sets `aria-expanded`. Defaults to whether the navbar drawer is open."
-          },
-          {
-            "name": "ref",
-            "required": false,
-            "type": "Ref<HTMLDivElement>",
-            "defaultValue": null,
-            "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
-          },
-          {
-            "name": "render",
-            "required": false,
-            "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, ButtonState>",
-            "defaultValue": null,
-            "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
-          },
-          {
-            "name": "style",
-            "required": false,
-            "type": "| CSSProperties\n| ((state: ButtonState) => CSSProperties)",
-            "defaultValue": null,
-            "description": "Style applied to the element, or a function that\nreturns a style object based on the component's state."
-          }
-        ]
-      },
       {
         "name": "AppShell.Footer",
         "description": "",
@@ -262,7 +207,7 @@
       },
       {
         "name": "AppShell.Header",
-        "description": "",
+        "description": "AppShell.Header — the page row: a title and actions at every width. Below `md` it sits under the shell's bar, and from\n`md` it sits beside the rail.",
         "props": [
           {
             "name": "ref",
@@ -297,11 +242,18 @@
             "defaultValue": null,
             "description": "The signed-in account at the foot of the rail, usually an `AccountCard`. Without it the foot is omitted."
           },
+          {
+            "name": "defaultOpen",
+            "required": false,
+            "type": "boolean",
+            "defaultValue": null,
+            "description": "Whether the drawer starts open when `open` is omitted."
+          },
           {
             "name": "logo",
             "required": false,
             "type": "ReactNode",
-            "defaultValue": "<ImFusionLogo variant={variant === \"branded\" ? \"oncolor\" : \"brand\"} size=\"sm\" />",
+            "defaultValue": "variant === \"branded\" ? oncolorLogo : brandLogo",
             "description": "The brand at the top of the rail. Defaults to the ImFusion logo; `null` leaves the row empty."
           },
           {
@@ -336,7 +288,7 @@
       },
       {
         "name": "AppShell.NavItem",
-        "description": "AppShell.NavItem — a navbar link: icon, mono label, and an optional description. Takes its color from the navbar;\n`aria-current=\"page\"` underlines the label. Pass a router link through `render`.",
+        "description": "AppShell.NavItem — a navbar link: icon, mono label, and an optional description. Takes its color from the navbar;\n`aria-current=\"page\"` underlines the label. Pass a router link through `render`. Followed inside the navbar drawer,\nit closes the drawer.",
         "props": [
           {
             "name": "description",
@@ -6715,6 +6667,13 @@
           "type": "SelectValueType<Value, Multiple> | null",
           "defaultValue": null,
           "description": "The value of the select. Use when controlled."
+        },
+        {
+          "name": "width",
+          "required": false,
+          "type": "\"auto\" | \"wide\" | \"full\" | null",
+          "defaultValue": "auto",
+          "description": "Trigger width: `auto` keeps the compact minimum; `wide` raises it; `full` fills the parent."
         }
       ]
     },

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

@@ -3,7 +3,8 @@ name: imf-web-ui
 description:
   "Route UI work and library questions in a project that uses @imfusion/web-ui. Use this skill whenever a user adds, edits,
   styles, or reviews UI, or asks about library setup, brand assets, favicons, theming, or usage in a consumer project, even
-  if they do not mention the library. Open only the matching packaged guide or companion skill."
+  if they do not mention the library. Also use it to link, unlink, or use a live local Web UI checkout. Open only the
+  matching packaged guide or companion skill."
 ---
 
 # Route Web UI work
@@ -23,18 +24,19 @@ may not already have. Open a companion by invoking its skill; reading one of its
 
 ## 2. Route the task
 
-| Task                                                                 | Open                       |
-| -------------------------------------------------------------------- | -------------------------- |
-| Understand library setup, brand assets, theming, or usage            | Packaged user guides below |
-| Look up a component, part, prop, default, or icon                    | `imf-web-ui-components`    |
-| Choose components or shape a screen, form, or flow                   | `imf-web-ui-ux`            |
-| Write or update documentation                                        | `imf-web-ui-conventions`   |
-| Write a wrapper, custom UI, CSS, data layer, validation, or tests    | `imf-web-ui-conventions`   |
-| Choose a routing, data, form, or validation library for the project  | `imf-web-ui-conventions`   |
-| Install the library or bootstrap project tooling                     | `imf-web-ui-setup`         |
-| Diagnose a broken install: unstyled output, missing tokens, no theme | `imf-web-ui-setup`         |
-| Inspect an existing project without changing it                      | `imf-web-ui-audit`         |
-| Update the package, skills, or hooks                                 | `imf-web-ui-update`        |
+| Task                                                                 | Open                                     |
+| -------------------------------------------------------------------- | ---------------------------------------- |
+| Understand library setup, brand assets, theming, or usage            | Packaged user guides below               |
+| Look up a component, part, prop, default, or icon                    | `imf-web-ui-components`                  |
+| Choose components or shape a screen, form, or flow                   | `imf-web-ui-ux`                          |
+| Write or update documentation                                        | `imf-web-ui-conventions`                 |
+| Write a wrapper, custom UI, CSS, data layer, validation, or tests    | `imf-web-ui-conventions`                 |
+| Choose a routing, data, form, or validation library for the project  | `imf-web-ui-conventions`                 |
+| Install the library or bootstrap project tooling                     | `imf-web-ui-setup`                       |
+| Diagnose a broken install: unstyled output, missing tokens, no theme | `imf-web-ui-setup`                       |
+| Inspect an existing project without changing it                      | `imf-web-ui-audit`                       |
+| Update the package, skills, or hooks                                 | `imf-web-ui-update`                      |
+| Link, unlink, or use a live local Web UI checkout                    | `imf-web-ui-conventions` `tooling` topic |
 
 A new form opens `imf-web-ui-ux`, even when its fields and action are already specified. A screen often needs both
 `imf-web-ui-ux` and `imf-web-ui-components`, in that order. Setup and audit are for project-wide questions, not every

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

@@ -60,7 +60,8 @@ Classify every result as one of these:
 
 Use the report contract's severity, `path:line` evidence, concrete impact, and smallest next action. Unverified entries use
 that same structure: unavailable runtime evidence, the impact of the unknown, and the check that resolves it. Do not promote
-an optional tool or a working alternative to a missing finding.
+an optional tool or a working alternative to a missing finding. A `vite.config.ts` without `localWebUILink()` registered from
+`@imfusion/web-ui/vite` is Missing. Its next action is the one-line add from the `tooling` topic.
 
 ## Topics
 

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

@@ -2,8 +2,9 @@
 name: imf-web-ui-conventions
 description:
   "Apply the ImFusion frontend conventions to consumer code. Use this whenever a task writes a wrapper or custom UI, CSS,
-  TypeScript, data fetching, validation, tests, project files, configuration, documentation, dependencies, or agent tooling
-  in a project that uses @imfusion/web-ui. Read only the topic references that match the task."
+  TypeScript, data fetching, validation, tests, project files, configuration, documentation, dependencies, linking a local
+  Web UI checkout, or agent tooling in a project that uses @imfusion/web-ui. Read only the topic references that match the
+  task."
 user-invocable: false
 ---
 
@@ -14,27 +15,27 @@ a gap or to make a deliberate deviation visible; do not refactor a project just
 
 ## Choose a topic
 
-| Topic                                            | Read when                                                       |
-| ------------------------------------------------ | --------------------------------------------------------------- |
-| [library-setup](topics/library-setup.md)         | Installing or repairing stylesheet and provider wiring.         |
-| [library-boundary](topics/library-boundary.md)   | Rendering, locking, or wrapping components, or choosing a peer. |
-| [authentication](topics/authentication.md)       | Protecting routes or defining login and logout.                 |
-| [react](topics/react.md)                         | Designing component roles, state ownership, or effects.         |
-| [components](topics/components.md)               | Adding files or deciding component anatomy.                     |
-| [typescript](topics/typescript.md)               | Writing TypeScript or naming values.                            |
-| [styling](topics/styling.md)                     | Writing CSS or customizing Web UI.                              |
-| [tokens](topics/tokens.md)                       | Choosing an exact token name.                                   |
-| [class-names](topics/class-names.md)             | Mapping variants and `className` to CSS.                        |
-| [validation](topics/validation.md)               | Accepting data from outside the frontend.                       |
-| [data](topics/data.md)                           | Adding API queries, mutations, or invalidation.                 |
-| [project-structure](topics/project-structure.md) | Adding files or routes.                                         |
-| [testing](topics/testing.md)                     | Deciding what to test.                                          |
-| [tooling](topics/tooling.md)                     | Adding a dependency or configuring a tool.                      |
-| [npm-project](topics/npm-project.md)             | Changing `package.json`, scripts, pins, or Node.                |
-| [git](topics/git.md)                             | Configuring hooks or choosing verification scope.               |
-| [agent-tooling](topics/agent-tooling.md)         | Installing skills or lifecycle hooks.                           |
-| [assets](topics/assets.md)                       | Adding images, icons, or other static files.                    |
-| [docs-structure](topics/docs-structure.md)       | Writing or reorganizing repository docs.                        |
+| Topic                                            | Read when                                                             |
+| ------------------------------------------------ | --------------------------------------------------------------------- |
+| [library-setup](topics/library-setup.md)         | Installing or repairing stylesheet and provider wiring.               |
+| [library-boundary](topics/library-boundary.md)   | Rendering, locking, or wrapping components, or choosing a peer.       |
+| [authentication](topics/authentication.md)       | Protecting routes or defining login and logout.                       |
+| [react](topics/react.md)                         | Designing component roles, state ownership, or effects.               |
+| [components](topics/components.md)               | Adding files or deciding component anatomy.                           |
+| [typescript](topics/typescript.md)               | Writing TypeScript or naming values.                                  |
+| [styling](topics/styling.md)                     | Writing CSS or customizing Web UI.                                    |
+| [tokens](topics/tokens.md)                       | Choosing an exact token name.                                         |
+| [class-names](topics/class-names.md)             | Mapping variants and `className` to CSS.                              |
+| [validation](topics/validation.md)               | Accepting data from outside the frontend.                             |
+| [data](topics/data.md)                           | Adding API queries, mutations, or invalidation.                       |
+| [project-structure](topics/project-structure.md) | Adding files or routes.                                               |
+| [testing](topics/testing.md)                     | Deciding what to test.                                                |
+| [tooling](topics/tooling.md)                     | Adding a dependency, configuring a tool, or linking a local checkout. |
+| [npm-project](topics/npm-project.md)             | Changing `package.json`, scripts, pins, or Node.                      |
+| [git](topics/git.md)                             | Configuring hooks or choosing verification scope.                     |
+| [agent-tooling](topics/agent-tooling.md)         | Installing skills or lifecycle hooks.                                 |
+| [assets](topics/assets.md)                       | Adding images, icons, or other static files.                          |
+| [docs-structure](topics/docs-structure.md)       | Writing or reorganizing repository docs.                              |
 
 ## How to use the topics
 

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

@@ -109,7 +109,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Oxfmt
 - [ ] Oxlint and TypeScript
 - [ ] Pre-commit checks
-- [ ] Vite plugins
+- [ ] Vite plugins, including `localWebUILink()`
 
 ## npm project — `npm-project`
 

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

@@ -70,8 +70,10 @@ Cross-topic invalidation can then use `keys.topic` instead of rebuilding a prefi
 
 ## Options factories and naming
 
-Queries use `get*` names such as `getAll`, `getById`, and `getDetails`. Mutations use bare verbs such as `update` or
-`delete`. Do not add a topic prefix or `Options` suffix; `context.api.user.getDetails()` already supplies the context.
+Queries use `get*` names such as `getAll`, `getById`, and `getDetails`. Mutations use verbs such as `update` or `delete`. A
+name never repeats its topic or adds an `Options` suffix; `context.api.user.getDetails()` already supplies the context. When
+a topic has more than one mutation target, add the sub-resource to the verb: `api.projects.removeMember(projectId)` and
+`api.projects.setMemberPermissions(projectId)`, where a bare `remove` would read as deleting the project.
 
 A query factory owns its key and parsing:
 

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

@@ -119,10 +119,10 @@ Register Web UI's Vite plugins in the application configuration:
 ```ts
 import { defineConfig } from "vite-plus";
 import react from "@vitejs/plugin-react";
-import { imfusionBrandAssets, readableCssModuleNames } from "@imfusion/web-ui/vite";
+import { imfusionBrandAssets, localWebUILink, readableCssModuleNames } from "@imfusion/web-ui/vite";
 
 export default defineConfig({
-  plugins: [react(), imfusionBrandAssets(), readableCssModuleNames({ prefix: "app" })]
+  plugins: [react(), imfusionBrandAssets(), readableCssModuleNames({ prefix: "app" }), localWebUILink()]
 });
 ```
 
@@ -130,5 +130,33 @@ export default defineConfig({
 Register `readableCssModuleNames` in every compiler that processes the app's CSS, including development, Storybook, and
 production. A compiler left out produces different class names and styles that appear to work only in some environments.
 
-`localWebUILink` dedupes the library's peer dependencies when `@imfusion/web-ui` is linked from a local checkout
-(`file:../web-ui`), so the app loads one React. It does nothing for an installed package and does not cover server rendering.
+`localWebUILink` keeps a local Web UI checkout linked for good. With no link it does nothing. After
+`npx web-ui link <checkout>` it serves the linked build without pre-bundling it and reloads the page on each sync;
+`npx web-ui unlink` restores the published package. Restart the dev server after either command, since the plugin reads the
+link when Vite starts. The plugin does not cover server rendering.
+
+## Enable or disable the live Web UI link
+
+Use this when a consumer must run against unreleased Web UI changes. The link copies the checkout's `dist/` into the
+consumer's installed package and syncs it after each rebuild, so uncommitted edits in the checkout reach the consumer too.
+
+To enable:
+
+1. Confirm `localWebUILink()` is registered in the consumer's `vite.config.ts`. If it is missing, ask before adding it.
+2. Find the checkout path: use `WEB_UI_CHECKOUT` when it is set, and ask otherwise.
+3. Start `npm run dev:lib` in the checkout as a background process. `web-ui link` refuses a checkout without `dist/`.
+4. Start `npx web-ui link <checkout>` in the consumer as a background process. It keeps running and syncs on each rebuild.
+5. Restart the consumer's dev server.
+6. Verify the rebuild arrives: after a rebuild, `diff -rq <checkout>/dist node_modules/@imfusion/web-ui/dist` prints nothing.
+
+To disable:
+
+1. Stop the background `web-ui link` and `npm run dev:lib` processes.
+2. Run `npx web-ui unlink` in the consumer.
+3. Restart the consumer's dev server.
+
+`npm install` and `npm ci` replace the linked package with the published one. After either, run `npx web-ui link <checkout>`
+again and restart the dev server.
+
+Do not commit while linked when the consumer's checks depend on unreleased Web UI API. They pass against the checkout and
+fail against the published package.

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

@@ -45,10 +45,17 @@ Include these pieces unless the existing project already has them or the user re
 - one server-backed current-user query at the route boundary;
 - a minimal `AppShell` in `_app/`, unless the user says the product has no persistent authenticated navigation;
 - an API topic folder for data shown by the first screen;
-- the root provider and library wiring.
+- the root provider and library wiring;
+- the Vite plugins below.
 
 The plan describes the exact starter files. It does not copy a generic starter project.
 
+## Vite plugins
+
+Propose a `vite.config.ts` that registers `imfusionBrandAssets()`, `readableCssModuleNames()`, and `localWebUILink()` from
+`@imfusion/web-ui/vite`, next to the plugins the project already has. Register `localWebUILink()` in every project: with no
+link it does nothing. The `tooling` topic has the exact config and the workflow for enabling a live link.
+
 ## Installer steps
 
 For `agent-tooling`, list the `npx web-ui install` commands as steps for the human. Read existing registrations first and do

package/dist/paths-B5Ht3ETc.js

@@ -1,26 +0,0 @@
-import { existsSync as e } from "node:fs";
-import { dirname as t, resolve as n } from "node:path";
-import { fileURLToPath as r } from "node:url";
-import { spawnSync as i } from "node:child_process";
-//#region src/cli/paths.ts
-function a(r) {
-	let i = r;
-	for (; !e(n(i, "package.json"));) {
-		let e = t(i);
-		if (e === i) throw Error(`Could not find package.json above ${r}`);
-		i = e;
-	}
-	return i;
-}
-var o = a(t(r(import.meta.url))), s = process.cwd();
-function c(r) {
-	let a = s;
-	for (; a !== t(a) && !e(n(a, "node_modules", ".bin"));) a = t(a);
-	let o = n(a, "node_modules", ".bin"), c = n(o, "vp"), [l, u] = e(c) ? [c, ["fmt", ...r]] : [n(o, "prettier"), ["--write", ...r]];
-	e(l) && i(l, u, {
-		cwd: s,
-		stdio: "ignore"
-	});
-}
-//#endregion
-export { o as n, s as r, c as t };