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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/README.md +19 -55
  2. package/dist/assets/vendors/base-ui.d.ts +2 -3
  3. package/dist/breakpoints/min-width.d.ts +3 -7
  4. package/dist/breakpoints/registry.d.ts +3 -9
  5. package/dist/{code-Ce8uiPsv.js → code-D2lwxHgd.js} +15 -15
  6. package/dist/codegen/gen-breakpoints-css.d.ts +0 -4
  7. package/dist/codegen/gen-token-css.d.ts +0 -2
  8. package/dist/components/app-shell/app-shell.d.ts +7 -11
  9. package/dist/components/button/button.d.ts +7 -12
  10. package/dist/components/callout/callout.d.ts +11 -18
  11. package/dist/components/card/card.d.ts +11 -10
  12. package/dist/components/checkbox/checkbox.d.ts +2 -38
  13. package/dist/components/chip/chip.cva.d.ts +2 -4
  14. package/dist/components/chip/chip.d.ts +1 -1
  15. package/dist/components/code/code.d.ts +2 -2
  16. package/dist/components/collapsible/collapsible.d.ts +4 -35
  17. package/dist/components/copy-button/copy-button.d.ts +1 -1
  18. package/dist/components/drawer/drawer.d.ts +17 -100
  19. package/dist/components/field/field.d.ts +7 -67
  20. package/dist/components/fieldset/fieldset.d.ts +2 -15
  21. package/dist/components/icon/icon.d.ts +2 -2
  22. package/dist/components/input/input.d.ts +2 -8
  23. package/dist/components/logo/imfusion/imfusion.d.ts +2 -5
  24. package/dist/components/logo/imfusion/marks.d.ts +10 -0
  25. package/dist/components/logo/logo.d.ts +3 -3
  26. package/dist/components/navigation-menu/subs/flyout-link.d.ts +5 -19
  27. package/dist/components/navigation-menu/subs/inline-submenu.d.ts +2 -4
  28. package/dist/components/navigation-menu/subs/link.d.ts +6 -23
  29. package/dist/components/navigation-menu/subs/overlay.d.ts +6 -51
  30. package/dist/components/navigation-menu/subs/shared.d.ts +4 -14
  31. package/dist/components/navigation-menu/subs/structure.d.ts +7 -29
  32. package/dist/components/navigation-menu/subs/trigger.d.ts +11 -20
  33. package/dist/components/number-field/index.d.ts +2 -0
  34. package/dist/components/number-field/number-field.d.ts +72 -0
  35. package/dist/components/number-field/number-field.meta.d.ts +2 -0
  36. package/dist/components/popover/popover.d.ts +23 -98
  37. package/dist/components/row/row.d.ts +1 -1
  38. package/dist/components/select/select.d.ts +26 -189
  39. package/dist/components/separator/separator.d.ts +5 -4
  40. package/dist/components/slider/slider.d.ts +7 -77
  41. package/dist/components/spinner/spinner.d.ts +13 -8
  42. package/dist/components/stack/stack.d.ts +3 -4
  43. package/dist/components/switch/switch.d.ts +2 -31
  44. package/dist/components/table/table.d.ts +10 -18
  45. package/dist/components/tabs/tabs.d.ts +18 -52
  46. package/dist/components/toast/toast.d.ts +16 -103
  47. package/dist/components/toggle/toggle.d.ts +3 -21
  48. package/dist/components/toggle-group/toggle-group.d.ts +3 -20
  49. package/dist/components/tooltip/tooltip.d.ts +26 -85
  50. package/dist/components/typo/typo.d.ts +25 -25
  51. package/dist/docgen/gen-docgen.utils.d.ts +3 -4
  52. package/dist/hooks/use-color-scheme.d.ts +5 -11
  53. package/dist/hooks/use-media-query.d.ts +2 -7
  54. package/dist/{icons-Cy1HAosO.js → icons-CaGCCwG-.js} +7 -7
  55. package/dist/icons.js +1 -1
  56. package/dist/index.d.ts +1 -0
  57. package/dist/index.js +1486 -1368
  58. package/dist/integrations/code-highlight/highlighter.d.ts +1 -56
  59. package/dist/integrations/code-highlight.js +41 -189
  60. package/dist/integrations/image-display-options/image-display-options-view.utils.d.ts +0 -1
  61. package/dist/integrations/image-display-options.js +54 -54
  62. package/dist/llms/evals/runner/affected.d.ts +2 -0
  63. package/dist/llms/evals/runner/benchmark.d.ts +12 -0
  64. package/dist/llms/evals/runner/compare.d.ts +2 -0
  65. package/dist/llms/evals/runner/config.d.ts +29 -0
  66. package/dist/llms/evals/runner/evidence.d.ts +7 -0
  67. package/dist/llms/evals/runner/execute.d.ts +32 -0
  68. package/dist/llms/evals/runner/grade.d.ts +10 -0
  69. package/dist/llms/evals/runner/report-md.d.ts +2 -0
  70. package/dist/llms/evals/runner/report.d.ts +4 -0
  71. package/dist/llms/evals/runner/run.d.ts +2 -0
  72. package/dist/llms/evals/runner/scenario.d.ts +3 -0
  73. package/dist/llms/evals/runner/types.d.ts +140 -0
  74. package/dist/llms/evals/runner/workspace.d.ts +2 -0
  75. package/dist/llms/evals/runner/write-generated.d.ts +1 -0
  76. package/dist/provider/web-ui-provider.d.ts +4 -1
  77. package/dist/style.css +1 -1
  78. package/dist/{tabs-DIe1Utiy.js → tabs-By5ir2pt.js} +162 -159
  79. package/dist/tokens/apply.d.ts +4 -9
  80. package/dist/tokens/control-registry.d.ts +3 -6
  81. package/dist/tokens/types.d.ts +7 -24
  82. package/dist/tokens/use-token-controls.d.ts +3 -12
  83. package/dist/types/meta.d.ts +15 -32
  84. package/dist/utils/index.d.ts +1 -0
  85. package/dist/utils/resolve-state-props.d.ts +4 -0
  86. package/dist/vite/brand-assets.d.ts +3 -0
  87. package/dist/vite/index.d.ts +2 -0
  88. package/dist/vite/readable-css-module-names.d.ts +11 -0
  89. package/dist/vite.js +55 -0
  90. package/dist/web-ui-cli.js +322 -0
  91. package/docs/user-guide/AgentTooling.mdx +127 -0
  92. package/docs/user-guide/BrandAssets.mdx +102 -0
  93. package/docs/user-guide/Changelog.mdx +23 -0
  94. package/docs/user-guide/GettingStarted.mdx +70 -0
  95. package/docs/user-guide/HowItsBuilt.mdx +113 -0
  96. package/docs/user-guide/Tokens.mdx +87 -0
  97. package/docs/user-guide/UsagePatterns.mdx +122 -0
  98. package/package.json +27 -22
  99. package/src/assets/public/favicon/apple-touch-icon.png +0 -0
  100. package/src/assets/public/favicon/favicon-16.png +0 -0
  101. package/src/assets/public/favicon/favicon-32.png +0 -0
  102. package/src/assets/public/favicon/favicon.ico +0 -0
  103. package/src/assets/public/favicon/favicon.svg +7 -0
  104. package/src/assets/public/favicon/icon-192.png +0 -0
  105. package/src/assets/public/favicon/icon-512.png +0 -0
  106. package/src/assets/public/favicon/og-image.png +0 -0
  107. package/src/assets/public/spinner/imfusion-spinner-black.webp +0 -0
  108. package/src/assets/public/spinner/imfusion-spinner-blue.webp +0 -0
  109. package/src/assets/public/spinner/imfusion-spinner-white.webp +0 -0
  110. package/src/docgen/doc.gen.json +3255 -603
  111. package/src/llms/install-templates/AGENTS.md +4 -4
  112. package/src/llms/install-templates/hooks/baseline-staleness.sh +9 -2
  113. package/src/llms/llms.gen.txt +7 -1
  114. package/src/llms/skills/imf-web-ui/SKILL.md +44 -21
  115. package/src/llms/skills/imf-web-ui-audit/SKILL.md +25 -11
  116. package/src/llms/skills/imf-web-ui-components/SKILL.md +4 -1
  117. package/src/llms/skills/imf-web-ui-conventions/SKILL.md +2 -2
  118. package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md +0 -1
  119. package/src/llms/skills/imf-web-ui-conventions/templates/REPORT.md +21 -2
  120. package/src/llms/skills/imf-web-ui-conventions/topics/agent-tooling.md +15 -10
  121. package/src/llms/skills/imf-web-ui-conventions/topics/assets.md +7 -4
  122. package/src/llms/skills/imf-web-ui-conventions/topics/data.md +3 -1
  123. package/src/llms/skills/imf-web-ui-conventions/topics/docs-structure.md +2 -2
  124. package/src/llms/skills/imf-web-ui-conventions/topics/git.md +4 -2
  125. package/src/llms/skills/imf-web-ui-conventions/topics/library-setup.md +10 -1
  126. package/src/llms/skills/imf-web-ui-conventions/topics/styling.md +2 -2
  127. package/src/llms/skills/imf-web-ui-conventions/topics/tokens.md +4 -2
  128. package/src/llms/skills/imf-web-ui-conventions/topics/tooling.md +13 -11
  129. package/src/llms/skills/imf-web-ui-setup/SKILL.md +17 -9
  130. package/src/llms/skills/imf-web-ui-update/SKILL.md +36 -14
  131. package/src/llms/skills/imf-web-ui-ux/SKILL.md +5 -3
  132. package/src/llms/tokens.gen.json +71 -7
  133. package/bin/install.js +0 -446
  134. package/dist/build/vite-css-module-names/index.d.ts +0 -20
  135. package/dist/build/vite-css-module-names.js +0 -17
  136. package/dist/components/spinner/spinner.geometry.d.ts +0 -37
  137. package/dist/integrations/code-highlight/languages/cmake.d.ts +0 -1
  138. package/dist/integrations/code-highlight/languages/cpp.d.ts +0 -1
  139. /package/dist/{meta-CySnRuVp.js → meta-j-7HGrWv.js} +0 -0
@@ -0,0 +1,102 @@
1
+ import { Meta } from "@storybook/addon-docs/blocks";
2
+ import faviconUrl from "#/assets/public/favicon/favicon.svg";
3
+ import ogUrl from "#/assets/public/favicon/og-image.png";
4
+
5
+ <Meta title="User Guide/Brand Assets" />
6
+
7
+ # Brand assets
8
+
9
+ The package ships the ImFusion favicon set and a social sharing image as plain files. Import them through the `assets`
10
+ subpath:
11
+
12
+ ```
13
+ @imfusion/web-ui/assets/<folder>/<file>
14
+ ```
15
+
16
+ These are static files rather than components, so an application references them from its HTML head, copies them into its own
17
+ output, or resolves them on disk during its build.
18
+
19
+ ## Files
20
+
21
+ | File | Size | Use |
22
+ | ------------------------------ | ---------- | --------------------------------------------------------- |
23
+ | `favicon/favicon.ico` | 16, 32, 48 | The fallback every browser understands |
24
+ | `favicon/favicon.svg` | any | Preferred by current browsers; stays sharp on any display |
25
+ | `favicon/favicon-16.png` | 16 | Explicit small PNG |
26
+ | `favicon/favicon-32.png` | 32 | Explicit standard PNG |
27
+ | `favicon/apple-touch-icon.png` | 180 | iOS home screen |
28
+ | `favicon/icon-192.png` | 192 | Web app manifest |
29
+ | `favicon/icon-512.png` | 512 | Web app manifest, splash screens |
30
+ | `favicon/og-image.png` | 1200×630 | Link previews in chat and social apps |
31
+
32
+ The mark sits on a square brand-blue tile. The white ImFusion glyph is scaled proportionally within it with a small inset at
33
+ the sides.
34
+
35
+ <div style={{ display: "flex", gap: "1.5rem", alignItems: "flex-end", margin: "1.5rem 0" }}>
36
+ {[16, 32, 64, 128].map(size => (
37
+ <div key={size} style={{ textAlign: "center" }}>
38
+ <img src={faviconUrl} width={size} height={size} alt="" style={{ display: "block", marginBottom: "0.5rem" }} />
39
+ <code style={{ fontSize: "0.75rem" }}>{size}</code>
40
+ </div>
41
+ ))}
42
+ </div>
43
+
44
+ <img src={ogUrl} alt="" width="480" style={{ display: "block", borderRadius: "0.5rem", margin: "1.5rem 0" }} />
45
+
46
+ ## Use the files
47
+
48
+ Pick the method that matches how the application builds:
49
+
50
+ | Method | Use it when | Public URLs |
51
+ | --- | --- | --- |
52
+ | [Vite plugin](#vite-plugin) | The application builds with Vite | Stable root paths such as `/favicon.ico` |
53
+ | [Copy step](#copy-step) | Another build system, or a static directory served as is | Whatever the copy target gives them |
54
+ | [Direct import](#direct-import) | One file used from application code, such as a manifest or an `<img>` | Hashed by the bundler |
55
+
56
+ ### Vite plugin
57
+
58
+ Register the plugin, then reference the stable root URLs from the document head:
59
+
60
+ ```ts
61
+ import { defineConfig } from "vite";
62
+ import { imfusionBrandAssets } from "@imfusion/web-ui/vite";
63
+
64
+ export default defineConfig({
65
+ plugins: [imfusionBrandAssets()]
66
+ });
67
+ ```
68
+
69
+ ```html
70
+ <link rel="icon" href="/favicon.ico" sizes="48x48" />
71
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
72
+ <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
73
+ <meta property="og:image" content="https://example.com/og-image.png" />
74
+ ```
75
+
76
+ The plugin serves the complete favicon set during development and emits it at the root of the build output. Give `og:image`
77
+ an absolute URL. Chat and social applications fetch it from their own servers, so a relative path does not resolve.
78
+
79
+ ### Copy step
80
+
81
+ Copy the files into the application's static-files directory during its build, then reference them from its HTML the same way
82
+ as above. Resolve the package path rather than hard-coding a path into `node_modules`:
83
+
84
+ ```ts
85
+ import { dirname } from "node:path";
86
+ import { fileURLToPath } from "node:url";
87
+
88
+ const faviconDir = dirname(fileURLToPath(import.meta.resolve("@imfusion/web-ui/assets/favicon/favicon.svg")));
89
+ ```
90
+
91
+ ### Direct import
92
+
93
+ A bundler can also take one file directly:
94
+
95
+ ```ts
96
+ import iconUrl from "@imfusion/web-ui/assets/favicon/icon-512.png";
97
+ ```
98
+
99
+ The bundler returns the asset's URL for use in application code. Vite also processes `index.html` and rewrites supported
100
+ asset references there. Use the plugin or the copy step when the files need stable public filenames.
101
+
102
+ <PageNav>Where behavior comes from, what Web UI adds on top, and why components are split into parts.</PageNav>
@@ -0,0 +1,23 @@
1
+ import { Meta } from "@storybook/addon-docs/blocks";
2
+
3
+ import { MarkdownDoc } from "#/storybook/docs/markdown-doc";
4
+ import { Separator } from "#/components/separator";
5
+ import { Typo } from "#/components/typo";
6
+
7
+ import doc from "../../CHANGELOG.md?raw";
8
+
9
+ <Meta title="User Guide/Changelog" />
10
+
11
+ <MarkdownDoc sourcePath="CHANGELOG.md" components={{
12
+ h1: <Typo.Hero />,
13
+ h2: <Typo.H1 />,
14
+ h3: <Typo.H2 />,
15
+ h4: <Typo.H3 />,
16
+ p: <Typo.P variant="primary" />,
17
+ ul: <Typo.UnorderedList variant="primary" />,
18
+ hr: <Separator spacing="spacious" variant="dashed" />
19
+ }}>
20
+ {doc}
21
+ </MarkdownDoc>
22
+
23
+ <PageNav>The token families, the control tokens that change them, and how to try them live.</PageNav>
@@ -0,0 +1,70 @@
1
+ import { Meta } from "@storybook/addon-docs/blocks";
2
+
3
+ <Meta title="User Guide/Getting Started" />
4
+
5
+ # Getting started
6
+
7
+ `@imfusion/web-ui` is the shared React UI library for ImFusion web apps. It provides accessible primitives, ImFusion tokens,
8
+ and one public import surface.
9
+
10
+ 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,
11
+ rather than follow a manual walkthrough.
12
+
13
+ ## 1. Install the package
14
+
15
+ ```sh
16
+ npm install @imfusion/web-ui
17
+ ```
18
+
19
+ The package requires React and React DOM 19 or newer.
20
+
21
+ ## 2. Install the agent skills
22
+
23
+ ```sh
24
+ npx web-ui install skills --harness=all
25
+ npx web-ui install hooks --harness=all
26
+ ```
27
+
28
+ This installs the skills an agent uses to work with the library. The hooks point the agent at the right skill for each task
29
+ and ask it to verify the project after it edits source files. [Agent Tooling](./AgentTooling.mdx) covers the flags and what
30
+ each piece does.
31
+
32
+ ## 3. Ask the agent to set up the library
33
+
34
+ Tell your agent, in plain language:
35
+
36
+ > Set up @imfusion/web-ui in this project.
37
+
38
+ Behind the scenes this runs the setup skill, `/imf-web-ui-setup`. It proposes a plan and writes the wiring only after you
39
+ approve it.
40
+
41
+ ## 4. What the agent writes
42
+
43
+ For an existing project, the agent adds the stylesheet import and mounts `WebUIProvider` once, near the application root:
44
+
45
+ ```tsx
46
+ import "@imfusion/web-ui/styles.css";
47
+ import { Button, WebUIProvider } from "@imfusion/web-ui";
48
+
49
+ export function App() {
50
+ return (
51
+ <WebUIProvider>
52
+ <Button>Save</Button>
53
+ </WebUIProvider>
54
+ );
55
+ }
56
+ ```
57
+
58
+ Import primitives from `@imfusion/web-ui`. Do not import Base UI components or styles directly.
59
+
60
+ An existing project that already has UI can also ask the agent for an audit. `/imf-web-ui-audit` checks the project against
61
+ the library's conventions and reports what it finds without changing any file.
62
+
63
+ For a new project, the same setup skill can also propose routing, an app shell, and other starter pieces. It writes only what
64
+ you approve.
65
+
66
+ ## Without an agent
67
+
68
+ Make the same two changes yourself: install the package, then add the stylesheet import and `WebUIProvider` shown above.
69
+
70
+ <PageNav>Which agents the tooling supports, the skills it installs, and the hooks that point an agent at them.</PageNav>
@@ -0,0 +1,113 @@
1
+ import { Meta } from "@storybook/addon-docs/blocks";
2
+
3
+ <Meta title="User Guide/How It's Built" />
4
+
5
+ # How it's built
6
+
7
+ You can use the library without knowing its implementation. The snippets below are simplified from the library source.
8
+
9
+ ## Behavior comes from an implementation library
10
+
11
+ Adapted interactive primitives use Base UI for focus management, keyboard behavior, and accessibility details. Web UI wraps
12
+ each part, takes its props from the upstream type, and adds its own class and identity:
13
+
14
+ ```tsx
15
+ import { Switch as Upstream } from "@base-ui/react/switch";
16
+
17
+ export function Root(props: React.ComponentProps<typeof Upstream.Root>) {
18
+ return <Upstream.Root {...props} data-imf-ui-component="Switch.Root" className={styles.root} />;
19
+ }
20
+ ```
21
+
22
+ Web UI owns the public props, defaults, tokens, styles, and exports. An application imports `Switch` from `@imfusion/web-ui`
23
+ and never sees `@base-ui/react`, so the implementation can change without forcing a consumer migration.
24
+
25
+ ## Web UI is the styled middle layer
26
+
27
+ Between the implementation library and the application, Web UI adds the look. Styles are CSS Modules that read `--imf-ui-*`
28
+ tokens, and two mechanisms pick which rules apply: CVA for the props a consumer sets, and data attributes for the state a
29
+ component is in at runtime.
30
+
31
+ ### Variants with CVA
32
+
33
+ [class-variance-authority](https://cva.style/docs) (CVA) maps each variant prop to a CSS Module class. The defaults sit in
34
+ the component signature:
35
+
36
+ ```tsx
37
+ import { cva } from "class-variance-authority";
38
+ import classes from "./button.module.css";
39
+
40
+ const button = cva(classes.root, {
41
+ variants: {
42
+ variant: { primary: classes.variantPrimary, outline: classes.variantOutline },
43
+ size: { sm: classes.sizeSm, md: classes.sizeMd }
44
+ }
45
+ });
46
+
47
+ export function Button({ variant = "primary", size = "md", className, ...props }: Props) {
48
+ return <Upstream {...props} data-imf-ui-component="Button" className={button({ variant, size, className })} />;
49
+ }
50
+ ```
51
+
52
+ A consumer `className` joins the variant classes instead of replacing them.
53
+
54
+ ### Runtime state with data attributes
55
+
56
+ State that changes while the component runs, such as checked, open, or disabled, is not a prop to map. Base UI sets it as
57
+ [data attributes](https://base-ui.com/react/handbook/styling#style-hooks) on each part, like `data-checked` on
58
+ `Switch.Root`, and the stylesheet selects them:
59
+
60
+ ```css
61
+ @layer imf-ui.components {
62
+ .root {
63
+ background: var(--imf-ui-color-bg-minor);
64
+ }
65
+
66
+ .root[data-checked] {
67
+ background: var(--imf-ui-color-bg-primary-main);
68
+ }
69
+ }
70
+ ```
71
+
72
+ Base UI's page for each component lists the attributes its parts expose.
73
+
74
+ ### Layers and tokens
75
+
76
+ Every rule sits in the `imf-ui.components` cascade layer. Unlayered CSS always beats layered CSS, so an application rule
77
+ wins without `!important`. The token changes the value everywhere; the rule changes one place:
78
+
79
+ ```css
80
+ :root {
81
+ --imf-ui-color-primary-hue: 30;
82
+ }
83
+
84
+ [data-imf-ui-component="Switch.Root"] {
85
+ border-radius: 0;
86
+ }
87
+ ```
88
+
89
+ The wrapper keeps the upstream surface complete. If an upstream part or prop is useful, Web UI exposes it instead of making an
90
+ app reach around the library.
91
+
92
+ ## Compose parts
93
+
94
+ Compound components are namespaces of parts. Instead of one component with a prop for every arrangement, an application
95
+ renders the parts it needs, where it needs them:
96
+
97
+ ```tsx
98
+ // One component, one prop per arrangement:
99
+ <Field label="Study name" description="Shown in the reading queue." descriptionPosition="above" />
100
+
101
+ // Parts, arranged by the application:
102
+ <Field.Root>
103
+ <Field.Label>Study name</Field.Label>
104
+ <Field.Description>Shown in the reading queue.</Field.Description>
105
+ <Input name="study" />
106
+ </Field.Root>
107
+ ```
108
+
109
+ The first form is pseudo-code; Web UI ships only the second. The
110
+ [library-boundary topic](../../src/llms/skills/imf-web-ui-conventions/topics/library-boundary.md) has the consumer import and
111
+ composition rules.
112
+
113
+ <PageNav>What changed in each release, with migration steps for breaking changes.</PageNav>
@@ -0,0 +1,87 @@
1
+ import { Meta } from "@storybook/addon-docs/blocks";
2
+
3
+ <Meta title="Tokens/Docs" />
4
+
5
+ # Tokens
6
+
7
+ The library's theme is a set of CSS custom properties under `--imf-ui-*`.
8
+
9
+ ## Change a family
10
+
11
+ Most customization uses a control token. Controls feed the semantic tokens consumed by components:
12
+
13
+ ```css
14
+ :root {
15
+ --imf-ui-color-brand-hue: 210;
16
+ }
17
+ ```
18
+
19
+ Brand and primary are related. Primary hue and chroma follow brand until their own controls are changed; primary luma is
20
+ independent. Surface controls work the same way: `main`, `support`, and `minor` start as one ladder and can be split when
21
+ needed.
22
+
23
+ Use a semantic token for a one-off role. That changes one result without changing the rest of its family.
24
+
25
+ ## Families
26
+
27
+ | Family | Use |
28
+ | --- | --- |
29
+ | Brand | Identity color. |
30
+ | Surfaces | Canvas and panels: `main`, `support`, `minor`. |
31
+ | Primary | Actions and calls to action. |
32
+ | Status | `negative`, `warning`, `positive`, and `info`. |
33
+ | Accents | Three independent accent slots. |
34
+ | Fonts | Shared font stacks and text roles. |
35
+ | Shape | Radius and corner controls. |
36
+ | Shadow | The shared elevation model. |
37
+
38
+ The live token controls and exact names are on the [token reference](../../src/tokens/token-reference.stories.tsx).
39
+
40
+ ## Use semantic tokens in CSS
41
+
42
+ Components and consumer CSS should use semantic roles:
43
+
44
+ ```css
45
+ .panel {
46
+ background: var(--imf-ui-color-bg-support);
47
+ color: var(--imf-ui-color-fg-main);
48
+ }
49
+ ```
50
+
51
+ Foreground tokens are for text, icons, borders, and focus rings. Background tokens are for fills. `fg-oncolor` is for text on
52
+ saturated fills.
53
+
54
+ ## Color schemes
55
+
56
+ The provider sets the active scheme on the document element:
57
+
58
+ ```html
59
+ <html data-imf-ui-color-scheme="light">
60
+ ```
61
+
62
+ Scheme-aware controls have light and dark values. Application CSS can select the attribute when a rule itself must change.
63
+
64
+ ## Fonts, shape, and shadow
65
+
66
+ The font controls define the editorial and utility type roles. Radius controls plain rounded corners; chamfer is a separate
67
+ brand shape axis. Shadow controls share one lighting model across components:
68
+
69
+ - `--imf-ui-shadow-angle` sets the sun direction; the default `315deg` makes shadows fall down and right.
70
+ - `--imf-ui-shadow-hardness` moves from diffuse (`0`) to crisp (`1`) edges without changing the elevation level.
71
+ - `--imf-ui-shadow-spread` adds pixel spread to every shadow.
72
+ - `--imf-ui-shadow-intensity` sets the lowest-level opacity; higher levels add one point each.
73
+ - `--imf-ui-shadow-color` sets the cast color per scheme.
74
+
75
+ Components consume these values through tokens. `node_modules/@imfusion/web-ui/src/llms/tokens.gen.json` lists the shipped
76
+ token names and authored defaults.
77
+
78
+ ## Explore
79
+
80
+ In Storybook, the Showcase and Reference pages show the token controls in a side panel on larger screens and behind the
81
+ `Tokens` button in the bottom-right corner on smaller ones. Other stories open the same drawer from that button. Changes
82
+ update the preview live; to keep a value, set that token in your application CSS.
83
+
84
+ - [Showcase](../../src/tokens/showcase.stories.tsx) applies the controls to real components.
85
+ - [Reference](../../src/tokens/token-reference.stories.tsx) lists every generated token.
86
+
87
+ <PageNav>What a primitive is, how compound parts compose, and what each component page shows.</PageNav>
@@ -0,0 +1,122 @@
1
+ import { Meta } from "@storybook/addon-docs/blocks";
2
+
3
+ <Meta title="User Guide/Usage Patterns" />
4
+
5
+ # Usage patterns
6
+
7
+ ## Build with components
8
+
9
+ Import components and the provider from `@imfusion/web-ui`, and icons from `@imfusion/web-ui/icons`. Multi-part
10
+ primitives are namespaces: render the parts a screen needs, in the order the component documents.
11
+
12
+ ```tsx
13
+ import { Field, Input } from "@imfusion/web-ui";
14
+
15
+ export function StudyName() {
16
+ return (
17
+ <Field.Root>
18
+ <Field.Label>Study name</Field.Label>
19
+ <Input name="study" />
20
+ <Field.Description>Shown in the reading queue.</Field.Description>
21
+ </Field.Root>
22
+ );
23
+ }
24
+ ```
25
+
26
+ The same pattern scales to an overlay. A drawer is a namespace too, and the field sits inside it unchanged:
27
+
28
+ ```tsx
29
+ import { Button, Drawer, Field, Input, Stack } from "@imfusion/web-ui";
30
+ import { Icon, Settings } from "@imfusion/web-ui/icons";
31
+
32
+ export function StudySettings() {
33
+ return (
34
+ <Drawer.Root>
35
+ <Drawer.Trigger render={<Button variant="secondary" startIcon={<Icon glyph={Settings} />}>Settings</Button>} />
36
+ <Drawer.Portal>
37
+ <Drawer.Backdrop />
38
+ <Drawer.Viewport>
39
+ <Drawer.Popup>
40
+ <Drawer.Content>
41
+ <Stack gap="4">
42
+ <Drawer.Title>Study settings</Drawer.Title>
43
+ <Field.Root>
44
+ <Field.Label>Study name</Field.Label>
45
+ <Input name="study" />
46
+ <Field.Description>Shown in the reading queue.</Field.Description>
47
+ </Field.Root>
48
+ <Drawer.Close render={<Button>Save</Button>} />
49
+ </Stack>
50
+ </Drawer.Content>
51
+ </Drawer.Popup>
52
+ </Drawer.Viewport>
53
+ </Drawer.Portal>
54
+ </Drawer.Root>
55
+ );
56
+ }
57
+ ```
58
+
59
+ Every part comes from `@imfusion/web-ui`, including less common ones such as `Drawer.Indent`, `Drawer.SwipeArea`, and
60
+ `Field.Description`. Do not import Base UI or another implementation package directly; the library's parts carry the styles,
61
+ defaults, and stable identity that the rest of this page relies on.
62
+
63
+ ## Change the look
64
+
65
+ 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
66
+ attribute changes one state.
67
+
68
+ ### With tokens
69
+
70
+ The theme is a set of `--imf-ui-*` custom properties. A control token changes a related family of semantic tokens at once:
71
+
72
+ ```css
73
+ :root {
74
+ --imf-ui-color-primary-hue: 30;
75
+ }
76
+ ```
77
+
78
+ [Tokens](./Tokens.mdx) lists the families, the controls, and how to try them live in Storybook.
79
+
80
+ ### With CSS
81
+
82
+ Consumer CSS outside `@layer imf-ui.components` overrides the library without `!important`:
83
+
84
+ ```css
85
+ .my-button {
86
+ border-radius: 0;
87
+ }
88
+ ```
89
+
90
+ Components carry `data-imf-ui-component` on their roots, so it is a stable selector. CSS Module class names are internal.
91
+
92
+ ### By state
93
+
94
+ Components expose runtime state through attributes such as `data-checked`, `data-disabled`, and `data-popup-open`:
95
+
96
+ ```css
97
+ [data-imf-ui-component="Switch.Root"][data-checked] {
98
+ outline: var(--imf-ui-border-size-2) solid var(--imf-ui-color-fg-positive);
99
+ }
100
+ ```
101
+
102
+ Use the attribute instead of maintaining a second state class.
103
+
104
+ ### By color scheme
105
+
106
+ `WebUIProvider` sets `data-imf-ui-color-scheme="light"` or `"dark"` on `<html>`. Select it when an application rule needs to
107
+ change with the scheme:
108
+
109
+ ```css
110
+ [data-imf-ui-color-scheme="dark"] .hero {
111
+ background-image: url("/hero-dark.png");
112
+ }
113
+ ```
114
+
115
+ The provider follows the OS by default. An application whose own surfaces are a fixed palette pins the scheme instead, so
116
+ component colors cannot disagree with them:
117
+
118
+ ```tsx
119
+ <WebUIProvider colorScheme="dark">{children}</WebUIProvider>
120
+ ```
121
+
122
+ <PageNav>The favicon set and social sharing image the package ships, and three ways to put them in an application.</PageNav>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@imfusion/web-ui",
3
- "version": "0.6.4-dev.8.g41d03f2f",
3
+ "version": "0.6.4-dev.84.gbfc0d437",
4
4
  "description": "The official Web UI component library for ImFusion web apps",
5
5
  "author": "ImFusion GmbH",
6
6
  "homepage": "https://imfusion.com",
@@ -20,7 +20,7 @@
20
20
  "module": "./dist/index.js",
21
21
  "types": "./dist/index.d.ts",
22
22
  "bin": {
23
- "web-ui-install": "bin/install.js"
23
+ "web-ui": "dist/web-ui-cli.js"
24
24
  },
25
25
  "exports": {
26
26
  ".": {
@@ -31,9 +31,9 @@
31
31
  "types": "./dist/integrations/*/index.d.ts",
32
32
  "import": "./dist/integrations/*.js"
33
33
  },
34
- "./build/*": {
35
- "types": "./dist/build/*/index.d.ts",
36
- "import": "./dist/build/*.js"
34
+ "./vite": {
35
+ "types": "./dist/vite/index.d.ts",
36
+ "import": "./dist/vite.js"
37
37
  },
38
38
  "./icons": {
39
39
  "types": "./dist/icons/index.d.ts",
@@ -42,28 +42,30 @@
42
42
  "./styles.css": "./dist/style.css",
43
43
  "./docgen.json": "./src/docgen/doc.gen.json",
44
44
  "./llms.txt": "./src/llms/llms.gen.txt",
45
+ "./assets/*": "./src/assets/public/*",
45
46
  "./*": null
46
47
  },
47
48
  "files": [
48
49
  "dist",
50
+ "src/assets/public",
49
51
  "docs/assets/imfusion-banner.svg",
52
+ "docs/user-guide",
50
53
  "THIRD_PARTY_NOTICES.md",
51
54
  "src/llms/install-templates",
52
55
  "src/docgen/doc.gen.json",
53
56
  "src/llms/llms.gen.txt",
54
57
  "src/llms/icon-catalog.gen.json",
55
58
  "src/llms/tokens.gen.json",
56
- "src/llms/skills",
57
- "bin/install.js"
59
+ "src/llms/skills"
58
60
  ],
59
61
  "scripts": {
60
62
  "dev": "tsx scripts/dev.ts",
61
63
  "dev:host": "tsx scripts/dev.ts --host",
62
64
  "dev:lib": "concurrently -n codegen,lib -c yellow,blue \"npm run codegen:watch\" \"vite build --watch\"",
63
- "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms && npm run codegen:tokens",
65
+ "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",
64
66
  "build:storybook": "npm run codegen:storybook && storybook build",
65
67
  "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",
66
- "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open",
68
+ "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open --ci",
67
69
  "storybook:free-ports": "tsx scripts/free-storybook-ports.ts",
68
70
  "codegen": "tsx src/codegen/run.ts",
69
71
  "codegen:watch": "tsx watch src/codegen/run.ts",
@@ -87,16 +89,17 @@
87
89
  "test:unit": "vitest run --project unit",
88
90
  "test:stories": "vitest run --project storybook",
89
91
  "test:watch": "vitest",
90
- "skills:eval": "node src/llms/evals/run.mjs",
91
- "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",
92
- "skills:eval:compare": "node src/llms/evals/compare.mjs",
93
- "skills:eval:report": "node src/llms/evals/report.mjs",
92
+ "skills:eval": "tsx src/llms/evals/runner/run.ts",
93
+ "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",
94
+ "skills:eval:compare": "tsx src/llms/evals/runner/compare.ts",
95
+ "skills:eval:affected": "tsx src/llms/evals/runner/affected.ts",
96
+ "skills:eval:report": "tsx src/llms/evals/runner/report.ts",
94
97
  "git:config": "git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only"
95
98
  },
96
99
  "peerDependencies": {
97
100
  "@imfusion/sdk": "^1.0.0 || >=1.1.1-dev.0 <1.1.1",
98
101
  "@imfusion/sdk-react": "^1.0.0 || >=1.1.1-dev.0 <1.1.1",
99
- "@tanstack/highlight": "^0.0.9",
102
+ "@tanstack/highlight": "^0.1.0",
100
103
  "react": "^19.0.0",
101
104
  "react-dom": "^19.0.0"
102
105
  },
@@ -115,6 +118,7 @@
115
118
  "@base-ui/react": "1.6.0",
116
119
  "@clack/prompts": "1.7.0",
117
120
  "class-variance-authority": "0.7.1",
121
+ "commander": "15.0.0",
118
122
  "iconoir-react": "7.12.1"
119
123
  },
120
124
  "devDependencies": {
@@ -122,12 +126,12 @@
122
126
  "@eslint/js": "9.39.4",
123
127
  "@imfusion/sdk": "1.0.0",
124
128
  "@imfusion/sdk-react": "1.0.0",
125
- "@storybook/addon-a11y": "10.4.3",
126
- "@storybook/addon-docs": "10.4.3",
127
- "@storybook/addon-mcp": "0.6.0",
128
- "@storybook/addon-vitest": "10.4.3",
129
- "@storybook/react-vite": "10.4.3",
130
- "@tanstack/highlight": "0.0.9",
129
+ "@storybook/addon-a11y": "10.6.0",
130
+ "@storybook/addon-docs": "10.6.0",
131
+ "@storybook/addon-mcp": "10.6.0",
132
+ "@storybook/addon-vitest": "10.6.0",
133
+ "@storybook/react-vite": "10.6.0",
134
+ "@tanstack/highlight": "0.1.0",
131
135
  "@tanstack/react-pacer": "0.22.1",
132
136
  "@types/culori": "4.0.1",
133
137
  "@types/mdx": "2.0.13",
@@ -148,11 +152,12 @@
148
152
  "jiti": "2.7.0",
149
153
  "knip": "6.14.2",
150
154
  "lightningcss": "1.32.0",
151
- "nano-staged": "1.0.2",
155
+ "mermaid": "12.0.0",
152
156
  "playwright": "1.60.0",
153
157
  "prettier": "3.8.3",
154
158
  "react-docgen-typescript": "2.4.0",
155
- "storybook": "10.4.3",
159
+ "remark-gfm": "4.0.1",
160
+ "storybook": "10.6.0",
156
161
  "tsx": "4.21.0",
157
162
  "typescript": "6.0.3",
158
163
  "typescript-eslint": "8.59.3",
@@ -0,0 +1,7 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
2
+ <rect width="512" height="512" fill="#245EFF" />
3
+ <g transform="translate(72 152) scale(1.168)">
4
+ <path d="M320 180H0V159.715L237.082 128.105L320 65.916V180Z" fill="#FFFFFF" />
5
+ <path d="M320 20.2832L82.918 51.8945L0 114.082V0H320V20.2832Z" fill="#FFFFFF" />
6
+ </g>
7
+ </svg>