@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.
- package/README.md +19 -55
- package/dist/assets/vendors/base-ui.d.ts +2 -3
- package/dist/breakpoints/min-width.d.ts +3 -7
- package/dist/breakpoints/registry.d.ts +3 -9
- package/dist/{code-Ce8uiPsv.js → code-D2lwxHgd.js} +15 -15
- package/dist/codegen/gen-breakpoints-css.d.ts +0 -4
- package/dist/codegen/gen-token-css.d.ts +0 -2
- package/dist/components/app-shell/app-shell.d.ts +7 -11
- package/dist/components/button/button.d.ts +7 -12
- package/dist/components/callout/callout.d.ts +11 -18
- package/dist/components/card/card.d.ts +11 -10
- package/dist/components/checkbox/checkbox.d.ts +2 -38
- package/dist/components/chip/chip.cva.d.ts +2 -4
- package/dist/components/chip/chip.d.ts +1 -1
- package/dist/components/code/code.d.ts +2 -2
- package/dist/components/collapsible/collapsible.d.ts +4 -35
- package/dist/components/copy-button/copy-button.d.ts +1 -1
- package/dist/components/drawer/drawer.d.ts +17 -100
- package/dist/components/field/field.d.ts +7 -67
- package/dist/components/fieldset/fieldset.d.ts +2 -15
- package/dist/components/icon/icon.d.ts +2 -2
- package/dist/components/input/input.d.ts +2 -8
- package/dist/components/logo/imfusion/imfusion.d.ts +2 -5
- package/dist/components/logo/imfusion/marks.d.ts +10 -0
- package/dist/components/logo/logo.d.ts +3 -3
- package/dist/components/navigation-menu/subs/flyout-link.d.ts +5 -19
- package/dist/components/navigation-menu/subs/inline-submenu.d.ts +2 -4
- package/dist/components/navigation-menu/subs/link.d.ts +6 -23
- package/dist/components/navigation-menu/subs/overlay.d.ts +6 -51
- package/dist/components/navigation-menu/subs/shared.d.ts +4 -14
- package/dist/components/navigation-menu/subs/structure.d.ts +7 -29
- package/dist/components/navigation-menu/subs/trigger.d.ts +11 -20
- package/dist/components/number-field/index.d.ts +2 -0
- package/dist/components/number-field/number-field.d.ts +72 -0
- package/dist/components/number-field/number-field.meta.d.ts +2 -0
- package/dist/components/popover/popover.d.ts +23 -98
- package/dist/components/row/row.d.ts +1 -1
- package/dist/components/select/select.d.ts +26 -189
- package/dist/components/separator/separator.d.ts +5 -4
- package/dist/components/slider/slider.d.ts +7 -77
- package/dist/components/spinner/spinner.d.ts +13 -8
- package/dist/components/stack/stack.d.ts +3 -4
- package/dist/components/switch/switch.d.ts +2 -31
- package/dist/components/table/table.d.ts +10 -18
- package/dist/components/tabs/tabs.d.ts +18 -52
- package/dist/components/toast/toast.d.ts +16 -103
- package/dist/components/toggle/toggle.d.ts +3 -21
- package/dist/components/toggle-group/toggle-group.d.ts +3 -20
- package/dist/components/tooltip/tooltip.d.ts +26 -85
- package/dist/components/typo/typo.d.ts +25 -25
- package/dist/docgen/gen-docgen.utils.d.ts +3 -4
- package/dist/hooks/use-color-scheme.d.ts +5 -11
- package/dist/hooks/use-media-query.d.ts +2 -7
- package/dist/{icons-Cy1HAosO.js → icons-CaGCCwG-.js} +7 -7
- package/dist/icons.js +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1486 -1368
- package/dist/integrations/code-highlight/highlighter.d.ts +1 -56
- package/dist/integrations/code-highlight.js +41 -189
- package/dist/integrations/image-display-options/image-display-options-view.utils.d.ts +0 -1
- package/dist/integrations/image-display-options.js +54 -54
- package/dist/llms/evals/runner/affected.d.ts +2 -0
- package/dist/llms/evals/runner/benchmark.d.ts +12 -0
- package/dist/llms/evals/runner/compare.d.ts +2 -0
- package/dist/llms/evals/runner/config.d.ts +29 -0
- package/dist/llms/evals/runner/evidence.d.ts +7 -0
- package/dist/llms/evals/runner/execute.d.ts +32 -0
- package/dist/llms/evals/runner/grade.d.ts +10 -0
- package/dist/llms/evals/runner/report-md.d.ts +2 -0
- package/dist/llms/evals/runner/report.d.ts +4 -0
- package/dist/llms/evals/runner/run.d.ts +2 -0
- package/dist/llms/evals/runner/scenario.d.ts +3 -0
- package/dist/llms/evals/runner/types.d.ts +140 -0
- package/dist/llms/evals/runner/workspace.d.ts +2 -0
- package/dist/llms/evals/runner/write-generated.d.ts +1 -0
- package/dist/provider/web-ui-provider.d.ts +4 -1
- package/dist/style.css +1 -1
- package/dist/{tabs-DIe1Utiy.js → tabs-By5ir2pt.js} +162 -159
- package/dist/tokens/apply.d.ts +4 -9
- package/dist/tokens/control-registry.d.ts +3 -6
- package/dist/tokens/types.d.ts +7 -24
- package/dist/tokens/use-token-controls.d.ts +3 -12
- package/dist/types/meta.d.ts +15 -32
- package/dist/utils/index.d.ts +1 -0
- package/dist/utils/resolve-state-props.d.ts +4 -0
- package/dist/vite/brand-assets.d.ts +3 -0
- package/dist/vite/index.d.ts +2 -0
- package/dist/vite/readable-css-module-names.d.ts +11 -0
- package/dist/vite.js +55 -0
- package/dist/web-ui-cli.js +322 -0
- package/docs/user-guide/AgentTooling.mdx +127 -0
- package/docs/user-guide/BrandAssets.mdx +102 -0
- package/docs/user-guide/Changelog.mdx +23 -0
- package/docs/user-guide/GettingStarted.mdx +70 -0
- package/docs/user-guide/HowItsBuilt.mdx +113 -0
- package/docs/user-guide/Tokens.mdx +87 -0
- package/docs/user-guide/UsagePatterns.mdx +122 -0
- package/package.json +27 -22
- package/src/assets/public/favicon/apple-touch-icon.png +0 -0
- package/src/assets/public/favicon/favicon-16.png +0 -0
- package/src/assets/public/favicon/favicon-32.png +0 -0
- package/src/assets/public/favicon/favicon.ico +0 -0
- package/src/assets/public/favicon/favicon.svg +7 -0
- package/src/assets/public/favicon/icon-192.png +0 -0
- package/src/assets/public/favicon/icon-512.png +0 -0
- package/src/assets/public/favicon/og-image.png +0 -0
- package/src/assets/public/spinner/imfusion-spinner-black.webp +0 -0
- package/src/assets/public/spinner/imfusion-spinner-blue.webp +0 -0
- package/src/assets/public/spinner/imfusion-spinner-white.webp +0 -0
- package/src/docgen/doc.gen.json +3255 -603
- package/src/llms/install-templates/AGENTS.md +4 -4
- package/src/llms/install-templates/hooks/baseline-staleness.sh +9 -2
- package/src/llms/llms.gen.txt +7 -1
- package/src/llms/skills/imf-web-ui/SKILL.md +44 -21
- package/src/llms/skills/imf-web-ui-audit/SKILL.md +25 -11
- package/src/llms/skills/imf-web-ui-components/SKILL.md +4 -1
- package/src/llms/skills/imf-web-ui-conventions/SKILL.md +2 -2
- package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md +0 -1
- package/src/llms/skills/imf-web-ui-conventions/templates/REPORT.md +21 -2
- package/src/llms/skills/imf-web-ui-conventions/topics/agent-tooling.md +15 -10
- package/src/llms/skills/imf-web-ui-conventions/topics/assets.md +7 -4
- package/src/llms/skills/imf-web-ui-conventions/topics/data.md +3 -1
- package/src/llms/skills/imf-web-ui-conventions/topics/docs-structure.md +2 -2
- package/src/llms/skills/imf-web-ui-conventions/topics/git.md +4 -2
- package/src/llms/skills/imf-web-ui-conventions/topics/library-setup.md +10 -1
- package/src/llms/skills/imf-web-ui-conventions/topics/styling.md +2 -2
- package/src/llms/skills/imf-web-ui-conventions/topics/tokens.md +4 -2
- package/src/llms/skills/imf-web-ui-conventions/topics/tooling.md +13 -11
- package/src/llms/skills/imf-web-ui-setup/SKILL.md +17 -9
- package/src/llms/skills/imf-web-ui-update/SKILL.md +36 -14
- package/src/llms/skills/imf-web-ui-ux/SKILL.md +5 -3
- package/src/llms/tokens.gen.json +71 -7
- package/bin/install.js +0 -446
- package/dist/build/vite-css-module-names/index.d.ts +0 -20
- package/dist/build/vite-css-module-names.js +0 -17
- package/dist/components/spinner/spinner.geometry.d.ts +0 -37
- package/dist/integrations/code-highlight/languages/cmake.d.ts +0 -1
- package/dist/integrations/code-highlight/languages/cpp.d.ts +0 -1
- /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.
|
|
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
|
|
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
|
-
"./
|
|
35
|
-
"types": "./dist/
|
|
36
|
-
"import": "./dist/
|
|
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": "
|
|
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'
|
|
92
|
-
"skills:eval:compare": "
|
|
93
|
-
"skills:eval:
|
|
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
|
|
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.
|
|
126
|
-
"@storybook/addon-docs": "10.
|
|
127
|
-
"@storybook/addon-mcp": "
|
|
128
|
-
"@storybook/addon-vitest": "10.
|
|
129
|
-
"@storybook/react-vite": "10.
|
|
130
|
-
"@tanstack/highlight": "0.0
|
|
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
|
-
"
|
|
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
|
-
"
|
|
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",
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -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>
|
|
Binary file
|
|
Binary file
|
|
Binary file
|