@imfusion/web-ui 0.6.4-dev.8.g41d03f2f → 0.7.0

package/docs/user-guide/GettingStarted.mdx

@@ -0,0 +1,71 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { Typo } from "#/components/typo";
+
+<Meta title="User Guide/Getting Started" />
+
+<Typo.Hero>Getting started</Typo.Hero>
+
+<Typo.Lead variant="primary">`@imfusion/web-ui` is the shared React UI library for ImFusion web apps. It provides accessible primitives, ImFusion tokens,
+and one public import surface.</Typo.Lead>
+
+The library is built to be set up and used through a coding agent. The recommended way to wire it up is to ask the agent,
+rather than follow a manual walkthrough.
+
+## 1. Install the package
+
+```sh
+npm install @imfusion/web-ui
+```
+
+The package requires React and React DOM 19 or newer.
+
+## 2. Install the agent skills
+
+```sh
+npx web-ui install skills --harness=all
+npx web-ui install hooks --harness=all
+```
+
+This installs the skills an agent uses to work with the library. The hooks point the agent at the right skill for each task
+and ask it to verify the project after it edits source files. [Agent Tooling](./AgentTooling.mdx) covers the flags and what
+each piece does.
+
+## 3. Ask the agent to set up the library
+
+Tell your agent, in plain language:
+
+> Set up @imfusion/web-ui in this project.
+
+Behind the scenes this runs the setup skill, `/imf-web-ui-setup`. It proposes a plan and writes the wiring only after you
+approve it.
+
+## 4. What the agent writes
+
+For an existing project, the agent adds the stylesheet import and mounts `WebUIProvider` once, near the application root:
+
+```tsx
+import "@imfusion/web-ui/styles.css";
+import { Button, WebUIProvider } from "@imfusion/web-ui";
+
+export function App() {
+  return (
+    <WebUIProvider>
+      <Button>Save</Button>
+    </WebUIProvider>
+  );
+}
+```
+
+Import primitives from `@imfusion/web-ui`. Do not import Base UI components or styles directly.
+
+An existing project that already has UI can also ask the agent for an audit. `/imf-web-ui-audit` checks the project against
+the library's conventions and reports what it finds without changing any file.
+
+For a new project, the same setup skill can also propose routing, an app shell, and other starter pieces. It writes only what
+you approve.
+
+## Without an agent
+
+Make the same two changes yourself: install the package, then add the stylesheet import and `WebUIProvider` shown above.
+
+<PageNav />

package/docs/user-guide/HowItsBuilt.mdx

@@ -0,0 +1,114 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { Typo } from "#/components/typo";
+
+<Meta title="User Guide/How It's Built" />
+
+<Typo.Hero>How it's built</Typo.Hero>
+
+You can use the library without knowing its implementation. The snippets below are simplified from the library source.
+
+## Behavior comes from an implementation library
+
+Adapted interactive primitives use Base UI for focus management, keyboard behavior, and accessibility details. Web UI wraps
+each part, takes its props from the upstream type, and adds its own class and identity:
+
+```tsx
+import { Switch as Upstream } from "@base-ui/react/switch";
+
+export function Root(props: React.ComponentProps<typeof Upstream.Root>) {
+  return <Upstream.Root {...props} data-imf-ui-component="Switch.Root" className={styles.root} />;
+}
+```
+
+Web UI owns the public props, defaults, tokens, styles, and exports. An application imports `Switch` from `@imfusion/web-ui`
+and never sees `@base-ui/react`, so the implementation can change without forcing a consumer migration.
+
+## Web UI is the styled middle layer
+
+Between the implementation library and the application, Web UI adds the look. Styles are CSS Modules that read `--imf-ui-*`
+tokens, and two mechanisms pick which rules apply: CVA for the props a consumer sets, and data attributes for the state a
+component is in at runtime.
+
+### Variants with CVA
+
+[class-variance-authority](https://cva.style/docs) (CVA) maps each variant prop to a CSS Module class. The defaults sit in
+the component signature:
+
+```tsx
+import { cva } from "class-variance-authority";
+import classes from "./button.module.css";
+
+const button = cva(classes.root, {
+  variants: {
+    variant: { primary: classes.variantPrimary, outline: classes.variantOutline },
+    size: { sm: classes.sizeSm, md: classes.sizeMd }
+  }
+});
+
+export function Button({ variant = "primary", size = "md", className, ...props }: Props) {
+  return <Upstream {...props} data-imf-ui-component="Button" className={button({ variant, size, className })} />;
+}
+```
+
+A consumer `className` joins the variant classes instead of replacing them.
+
+### Runtime state with data attributes
+
+State that changes while the component runs, such as checked, open, or disabled, is not a prop to map. Base UI sets it as
+[data attributes](https://base-ui.com/react/handbook/styling#style-hooks) on each part, like `data-checked` on
+`Switch.Root`, and the stylesheet selects them:
+
+```css
+@layer imf-ui.components {
+  .root {
+    background: var(--imf-ui-color-bg-minor);
+  }
+
+  .root[data-checked] {
+    background: var(--imf-ui-color-bg-primary-main);
+  }
+}
+```
+
+Base UI's page for each component lists the attributes its parts expose.
+
+### Layers and tokens
+
+Every rule sits in the `imf-ui.components` cascade layer. Unlayered CSS always beats layered CSS, so an application rule
+wins without `!important`. The token changes the value everywhere; the rule changes one place:
+
+```css
+:root {
+  --imf-ui-color-primary-hue: 30;
+}
+
+[data-imf-ui-component="Switch.Root"] {
+  border-radius: 0;
+}
+```
+
+The wrapper keeps the upstream surface complete. If an upstream part or prop is useful, Web UI exposes it instead of making an
+app reach around the library.
+
+## Compose parts
+
+Compound components are namespaces of parts. Instead of one component with a prop for every arrangement, an application
+renders the parts it needs, where it needs them:
+
+```tsx
+// One component, one prop per arrangement:
+<Field label="Study name" description="Shown in the reading queue." descriptionPosition="above" />
+
+// Parts, arranged by the application:
+<Field.Root>
+  <Field.Label>Study name</Field.Label>
+  <Field.Description>Shown in the reading queue.</Field.Description>
+  <Input name="study" />
+</Field.Root>
+```
+
+The first form is pseudo-code; Web UI ships only the second. The
+[library-boundary topic](../../src/llms/skills/imf-web-ui-conventions/topics/library-boundary.md) has the consumer import and
+composition rules.
+
+<PageNav />

package/docs/user-guide/Tokens.mdx

@@ -0,0 +1,88 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { Typo } from "#/components/typo";
+
+<Meta title="Tokens/Docs" />
+
+<Typo.Hero>Tokens</Typo.Hero>
+
+The library's theme is a set of CSS custom properties under `--imf-ui-*`.
+
+## Change a family
+
+Most customization uses a control token. Controls feed the semantic tokens consumed by components:
+
+```css
+:root {
+  --imf-ui-color-brand-hue: 210;
+}
+```
+
+Brand and primary are related. Primary hue and chroma follow brand until their own controls are changed; primary luma is
+independent. Surface controls work the same way: `main`, `support`, and `minor` start as one ladder and can be split when
+needed.
+
+Use a semantic token for a one-off role. That changes one result without changing the rest of its family.
+
+## Families
+
+| Family | Use |
+| --- | --- |
+| Brand | Identity color. |
+| Surfaces | Canvas and panels: `main`, `support`, `minor`. |
+| Primary | Actions and calls to action. |
+| Status | `negative`, `warning`, `positive`, and `info`. |
+| Accents | Three independent accent slots. |
+| Fonts | Shared font stacks and text roles. |
+| Shape | Radius and corner controls. |
+| Shadow | The shared elevation model. |
+
+The live token controls and exact names are on the [token reference](../../src/tokens/token-reference.stories.tsx).
+
+## Use semantic tokens in CSS
+
+Components and consumer CSS should use semantic roles:
+
+```css
+.panel {
+  background: var(--imf-ui-color-bg-support);
+  color: var(--imf-ui-color-fg-main);
+}
+```
+
+Foreground tokens are for text, icons, borders, and focus rings. Background tokens are for fills. `fg-oncolor` is for text on
+saturated fills.
+
+## Color schemes
+
+The provider sets the active scheme on the document element:
+
+```html
+<html data-imf-ui-color-scheme="light">
+```
+
+Scheme-aware controls have light and dark values. Application CSS can select the attribute when a rule itself must change.
+
+## Fonts, shape, and shadow
+
+The font controls define the editorial and utility type roles. Radius controls plain rounded corners; chamfer is a separate
+brand shape axis. Shadow controls share one lighting model across components:
+
+- `--imf-ui-shadow-angle` sets the sun direction; the default `315deg` makes shadows fall down and right.
+- `--imf-ui-shadow-hardness` moves from diffuse (`0`) to crisp (`1`) edges without changing the elevation level.
+- `--imf-ui-shadow-spread` adds pixel spread to every shadow.
+- `--imf-ui-shadow-intensity` sets the opacity of every elevation level.
+- `--imf-ui-shadow-color` sets the cast color per scheme.
+
+Components consume these values through tokens. `node_modules/@imfusion/web-ui/src/llms/tokens.gen.json` lists the shipped
+token names and authored defaults.
+
+## Explore
+
+In Storybook, the Showcase and Reference pages show the token controls in a side panel on larger screens and behind the
+`Tokens` button in the bottom-right corner on smaller ones. Other stories open the same drawer from that button. Changes
+update the preview live; to keep a value, set that token in your application CSS.
+
+- [Showcase](../../src/tokens/showcase.stories.tsx) applies the controls to real components.
+- [Reference](../../src/tokens/token-reference.stories.tsx) lists every generated token.
+
+<PageNav />

package/docs/user-guide/UsagePatterns.mdx

@@ -0,0 +1,123 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+import { Typo } from "#/components/typo";
+
+<Meta title="User Guide/Usage Patterns" />
+
+<Typo.Hero>Usage patterns</Typo.Hero>
+
+## Build with components
+
+Import components and the provider from `@imfusion/web-ui`, and icons from `@imfusion/web-ui/icons`. Multi-part
+primitives are namespaces: render the parts a screen needs, in the order the component documents.
+
+```tsx
+import { Field, Input } from "@imfusion/web-ui";
+
+export function StudyName() {
+  return (
+    <Field.Root>
+      <Field.Label>Study name</Field.Label>
+      <Input name="study" />
+      <Field.Description>Shown in the reading queue.</Field.Description>
+    </Field.Root>
+  );
+}
+```
+
+The same pattern scales to an overlay. A drawer is a namespace too, and the field sits inside it unchanged:
+
+```tsx
+import { Button, Drawer, Field, Input, Stack } from "@imfusion/web-ui";
+import { Icon, Settings } from "@imfusion/web-ui/icons";
+
+export function StudySettings() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger render={<Button variant="secondary" startIcon={<Icon glyph={Settings} />}>Settings</Button>} />
+      <Drawer.Portal>
+        <Drawer.Backdrop />
+        <Drawer.Viewport>
+          <Drawer.Popup>
+            <Drawer.Content>
+              <Stack gap="4">
+                <Drawer.Title>Study settings</Drawer.Title>
+                <Field.Root>
+                  <Field.Label>Study name</Field.Label>
+                  <Input name="study" />
+                  <Field.Description>Shown in the reading queue.</Field.Description>
+                </Field.Root>
+                <Drawer.Close render={<Button>Save</Button>} />
+              </Stack>
+            </Drawer.Content>
+          </Drawer.Popup>
+        </Drawer.Viewport>
+      </Drawer.Portal>
+    </Drawer.Root>
+  );
+}
+```
+
+Every part comes from `@imfusion/web-ui`, including less common ones such as `Drawer.Indent`, `Drawer.SwipeArea`, and
+`Field.Description`. Do not import Base UI or another implementation package directly; the library's parts carry the styles,
+defaults, and stable identity that the rest of this page relies on.
+
+## Change the look
+
+Start as broad as the change is, then narrow down: a token changes a whole family, a CSS rule changes one place, and a state
+attribute changes one state.
+
+### With tokens
+
+The theme is a set of `--imf-ui-*` custom properties. A control token changes a related family of semantic tokens at once:
+
+```css
+:root {
+  --imf-ui-color-primary-hue: 30;
+}
+```
+
+[Tokens](./Tokens.mdx) lists the families, the controls, and how to try them live in Storybook.
+
+### With CSS
+
+Consumer CSS outside `@layer imf-ui.components` overrides the library without `!important`:
+
+```css
+.my-button {
+  border-radius: 0;
+}
+```
+
+Components carry `data-imf-ui-component` on their roots, so it is a stable selector. CSS Module class names are internal.
+
+### By state
+
+Components expose runtime state through attributes such as `data-checked`, `data-disabled`, and `data-popup-open`:
+
+```css
+[data-imf-ui-component="Switch.Root"][data-checked] {
+  outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-positive);
+}
+```
+
+Use the attribute instead of maintaining a second state class.
+
+### By color scheme
+
+`WebUIProvider` sets `data-imf-ui-color-scheme="light"` or `"dark"` on `<html>`. Select it when an application rule needs to
+change with the scheme:
+
+```css
+[data-imf-ui-color-scheme="dark"] .hero {
+  background-image: url("/hero-dark.png");
+}
+```
+
+The provider follows the OS by default. An application whose own surfaces are a fixed palette pins the scheme instead, so
+component colors cannot disagree with them:
+
+```tsx
+<WebUIProvider colorScheme="dark">{children}</WebUIProvider>
+```
+
+<PageNav />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imfusion/web-ui",
-  "version": "0.6.4-dev.8.g41d03f2f",
+  "version": "0.7.0",
   "description": "The official Web UI component library for ImFusion web apps",
   "author": "ImFusion GmbH",
   "homepage": "https://imfusion.com",
@@ -20,7 +20,7 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "web-ui-install": "bin/install.js"
+    "web-ui": "dist/web-ui-cli.js"
   },
   "exports": {
     ".": {
@@ -31,9 +31,9 @@
       "types": "./dist/integrations/*/index.d.ts",
       "import": "./dist/integrations/*.js"
     },
-    "./build/*": {
-      "types": "./dist/build/*/index.d.ts",
-      "import": "./dist/build/*.js"
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "import": "./dist/vite.js"
     },
     "./icons": {
       "types": "./dist/icons/index.d.ts",
@@ -42,28 +42,31 @@
     "./styles.css": "./dist/style.css",
     "./docgen.json": "./src/docgen/doc.gen.json",
     "./llms.txt": "./src/llms/llms.gen.txt",
+    "./assets/*": "./src/assets/public/*",
     "./*": null
   },
   "files": [
     "dist",
+    "src/assets/public",
     "docs/assets/imfusion-banner.svg",
+    "docs/user-guide",
+    "CHANGELOG.md",
     "THIRD_PARTY_NOTICES.md",
     "src/llms/install-templates",
     "src/docgen/doc.gen.json",
     "src/llms/llms.gen.txt",
     "src/llms/icon-catalog.gen.json",
     "src/llms/tokens.gen.json",
-    "src/llms/skills",
-    "bin/install.js"
+    "src/llms/skills"
   ],
   "scripts": {
     "dev": "tsx scripts/dev.ts",
     "dev:host": "tsx scripts/dev.ts --host",
     "dev:lib": "concurrently -n codegen,lib -c yellow,blue \"npm run codegen:watch\" \"vite build --watch\"",
-    "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms && npm run codegen:tokens",
+    "build": "npm run codegen && rm -rf dist && vite build && chmod +x dist/web-ui-cli.js && npm run codegen:docgen && npm run codegen:llms && npm run codegen:tokens",
     "build:storybook": "npm run codegen:storybook && storybook build",
     "ci:status": "teamcity run list --job WebSDK_WebUI_BuildTest --limit 3 --json=id,number,status,state,branchName,buildType.name,triggered.type,triggered.user.name,startDate,finishDate,webUrl | tsx scripts/ci-status.ts",
-    "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open",
+    "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open --ci",
     "storybook:free-ports": "tsx scripts/free-storybook-ports.ts",
     "codegen": "tsx src/codegen/run.ts",
     "codegen:watch": "tsx watch src/codegen/run.ts",
@@ -87,16 +90,17 @@
     "test:unit": "vitest run --project unit",
     "test:stories": "vitest run --project storybook",
     "test:watch": "vitest",
-    "skills:eval": "node src/llms/evals/run.mjs",
-    "skills:eval:dev": "WEB_UI_SKILL_EVAL_ROOT=/private/tmp/web-ui-dev-skill-evals WEB_UI_SKILL_EVAL_RESULTS_DIR=.agents/evals/results WEB_UI_SKILL_EVAL_REPORT_PATH=.agents/evals/REPORT.md WEB_UI_SKILL_EVAL_SKILL_FAMILY=web-ui-dev WEB_UI_SKILL_EVAL_WORKSPACE_LABEL='development repository' node src/llms/evals/run.mjs --scenarios-dir .agents/evals/scenarios --setup .agents/evals/setup-env.sh",
-    "skills:eval:compare": "node src/llms/evals/compare.mjs",
-    "skills:eval:report": "node src/llms/evals/report.mjs",
+    "skills:eval": "tsx src/llms/evals/runner/run.ts",
+    "skills:eval:dev": "WEB_UI_SKILL_EVAL_ROOT=/private/tmp/web-ui-dev-skill-evals WEB_UI_SKILL_EVAL_RESULTS_DIR=.agents/evals/results WEB_UI_SKILL_EVAL_REPORT_PATH=.agents/evals/REPORT.md WEB_UI_SKILL_EVAL_SKILL_FAMILY=web-ui-dev WEB_UI_SKILL_EVAL_WORKSPACE_LABEL='development repository' tsx src/llms/evals/runner/run.ts --scenarios-dir .agents/evals/scenarios --setup .agents/evals/setup-env.sh",
+    "skills:eval:compare": "tsx src/llms/evals/runner/compare.ts",
+    "skills:eval:affected": "tsx src/llms/evals/runner/affected.ts",
+    "skills:eval:report": "tsx src/llms/evals/runner/report.ts",
     "git:config": "git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only"
   },
   "peerDependencies": {
     "@imfusion/sdk": "^1.0.0 || >=1.1.1-dev.0 <1.1.1",
     "@imfusion/sdk-react": "^1.0.0 || >=1.1.1-dev.0 <1.1.1",
-    "@tanstack/highlight": "^0.0.9",
+    "@tanstack/highlight": "^0.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
@@ -115,6 +119,7 @@
     "@base-ui/react": "1.6.0",
     "@clack/prompts": "1.7.0",
     "class-variance-authority": "0.7.1",
+    "commander": "15.0.0",
     "iconoir-react": "7.12.1"
   },
   "devDependencies": {
@@ -122,12 +127,12 @@
     "@eslint/js": "9.39.4",
     "@imfusion/sdk": "1.0.0",
     "@imfusion/sdk-react": "1.0.0",
-    "@storybook/addon-a11y": "10.4.3",
-    "@storybook/addon-docs": "10.4.3",
-    "@storybook/addon-mcp": "0.6.0",
-    "@storybook/addon-vitest": "10.4.3",
-    "@storybook/react-vite": "10.4.3",
-    "@tanstack/highlight": "0.0.9",
+    "@storybook/addon-a11y": "10.6.0",
+    "@storybook/addon-docs": "10.6.0",
+    "@storybook/addon-mcp": "10.6.0",
+    "@storybook/addon-vitest": "10.6.0",
+    "@storybook/react-vite": "10.6.0",
+    "@tanstack/highlight": "0.1.0",
     "@tanstack/react-pacer": "0.22.1",
     "@types/culori": "4.0.1",
     "@types/mdx": "2.0.13",
@@ -148,11 +153,12 @@
     "jiti": "2.7.0",
     "knip": "6.14.2",
     "lightningcss": "1.32.0",
-    "nano-staged": "1.0.2",
+    "mermaid": "12.0.0",
     "playwright": "1.60.0",
     "prettier": "3.8.3",
     "react-docgen-typescript": "2.4.0",
-    "storybook": "10.4.3",
+    "remark-gfm": "4.0.1",
+    "storybook": "10.6.0",
     "tsx": "4.21.0",
     "typescript": "6.0.3",
     "typescript-eslint": "8.59.3",

package/src/assets/public/favicon/favicon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" fill="#245EFF" />
+  <g transform="translate(72 152) scale(1.168)">
+    <path d="M320 180H0V159.715L237.082 128.105L320 65.916V180Z" fill="#FFFFFF" />
+    <path d="M320 20.2832L82.918 51.8945L0 114.082V0H320V20.2832Z" fill="#FFFFFF" />
+  </g>
+</svg>