@imfusion/web-ui 0.5.0

package/dist/tokens/apply.d.ts

@@ -0,0 +1,55 @@
+import { ColorScheme } from '../types/theme';
+import { Token, TokenControl, TokenId } from './token-registry';
+import { TokenOverrides } from './types';
+/**
+ * Pure token-application layer — no React, no router, no DOM ownership beyond the one imperative
+ * writer ({@link applyTokenOverrides}). The stateful, persistence-agnostic hook is `useTokenControls`.
+ */
+/** Flatten a possibly scheme-keyed numeric value to the active scheme. */
+export declare function resolveScheme(field: number | Record<ColorScheme, number>, scheme: ColorScheme): number;
+/**
+ * A control resolved to the active scheme — the panel-facing view. Slider controls carry numeric
+ * bounds; select controls carry options.
+ */
+export type ResolvedControl = {
+    id: TokenId;
+    cssVar: string;
+    group: Token["group"];
+    label: string;
+    description: string;
+} & ({
+    kind: "slider";
+    type: "single" | "shared";
+    value: number;
+    defaultValue: number;
+    min: number;
+    max: number;
+    step: number;
+    derivedFrom?: TokenId;
+} | {
+    kind: "select";
+    value: string;
+    defaultValue: string;
+    options: readonly {
+        label: string;
+        value: string;
+    }[];
+});
+/**
+ * Resolve a control to the active scheme, flattening its scheme-keyed fields to plain numbers.
+ * `value` starts at the resolved default; callers overlay effective overrides.
+ */
+export declare function resolve(control: TokenControl, scheme: ColorScheme): ResolvedControl;
+/**
+ * Registry-driven effective overrides — any slider control with `derivedFrom` tracks its source token
+ * until explicitly touched. Mirrors the CSS `var(--src, fallback)` chain so slider display stays
+ * correct. Select controls have no derivation.
+ */
+export declare function deriveAll(live: TokenOverrides): TokenOverrides;
+/**
+ * Imperative core — reconcile `documentElement`'s inline custom properties to `overrides`. Sets
+ * present vars, removes every registry var absent from `overrides` (both `-light`/`-dark`), so reset
+ * and scheme switches leave nothing stale. This is the one DOM writer; `useTokenControls` calls it in
+ * a layout effect, and hosts (Storybook, consumers) can call it directly.
+ */
+export declare function applyTokenOverrides(overrides: TokenOverrides, root?: HTMLElement): void;

package/dist/tokens/control-registry.d.ts

@@ -0,0 +1,10 @@
+import { TokenControl } from './token-registry';
+/**
+ * The control registry — every {@link TokenControl}, i.e. every token that has a live adjuster. Each
+ * entry spreads its token's data (including `label`/`description`) from `TOKEN_REGISTRY` and adds
+ * only the control-specific metadata its UI needs.
+ *
+ * Not every token appears here: the semantic font aliases (`font-family-heading` / `-body` / `-ui`
+ * / `-code`) are `var()` indirections with no direct control, so they have no entry.
+ */
+export declare const TOKEN_CONTROLS: readonly TokenControl[];

package/dist/tokens/token-registry.d.ts

@@ -0,0 +1,13 @@
+import { Token, TokenId, TokenValue } from './types';
+/**
+ * Derive the CSS custom property for a token. Scheme-aware tokens (numeric `Record<ColorScheme>`
+ * default) get a `-${scheme}` suffix; every other token has a single var.
+ */
+export declare function toTokenCssVar(token: {
+    id: string;
+    default: TokenValue;
+}, scheme: "light" | "dark"): string;
+export declare const TOKEN_REGISTRY: Record<TokenId, Token>;
+export type { Token, TokenControl, TokenGroup, TokenId } from './types';
+/** Runtime lookup: token by id. Always present — `TokenId` is exactly `TOKEN_REGISTRY`'s key set. */
+export declare function tokenById(id: TokenId): Token;

package/dist/tokens/types.d.ts

@@ -0,0 +1,71 @@
+import { ColorScheme } from '../types/theme';
+/**
+ * A **token** is a CSS custom property under `--imf-ui-` carrying a design value; every token lives
+ * in `TOKEN_REGISTRY`. A **TokenControl** is a live adjuster *bound to* a token, not a kind of token —
+ * it carries the token's own fields plus the control's `id`. Not every token has a control.
+ *
+ * The shapes below are generic over the id type to avoid an import cycle with the registry that
+ * defines the concrete `TokenId` union. Import `Token` / `TokenControl` from `./token-registry` (bound
+ * to the concrete id), not from here directly.
+ */
+/** A continuous or per-scheme numeric value (slider tokens) or a fixed string (select tokens). */
+export type TokenValue = number | string | Record<ColorScheme, number>;
+/** A numeric value that may be resolved per color scheme (min / max / default on slider controls). */
+export type NumericTokenValue = number | Record<ColorScheme, number>;
+/** Grouping for panel layout. */
+export type TokenGroup = "brand" | "surface" | "primary" | "status" | "accent" | "shadow" | "shape" | "font";
+/**
+ * The canonical token id vocabulary — **hand-authored** (not derived from the registry). This is the
+ * source of truth for what a `--imf-ui-*` token may be called, so:
+ * - the registry definition site gets autocomplete and rejects typos (`TOKEN_REGISTRY` is a
+ *   `Record<TokenId, Token>`, so every key and every `id` is checked against it);
+ * - every `id` / `derivedFrom` on a control is checked against it.
+ *
+ * Adding or renaming a token is a deliberate two-step edit: this union **and** `TOKEN_REGISTRY`. The
+ * `token-registry.test.ts` "union ↔ registry agree" test fails loudly if the two drift.
+ */
+export type TokenId = "color-brand-luma" | "color-brand-chroma" | "color-brand-hue" | "color-surface-bg-luma" | "color-surface-fg-luma" | "color-surface-chroma" | "color-surface-main-hue" | "color-surface-support-hue" | "color-surface-minor-hue" | "color-primary-bg-luma" | "color-primary-fg-luma" | "color-primary-chroma" | "color-primary-hue" | "color-status-bg-luma" | "color-status-fg-luma" | "color-status-chroma" | "color-status-positive-hue" | "color-status-negative-hue" | "color-status-warning-hue" | "color-status-info-hue" | "color-accent-1-bg-luma" | "color-accent-1-fg-luma" | "color-accent-1-chroma" | "color-accent-1-hue" | "color-accent-2-bg-luma" | "color-accent-2-fg-luma" | "color-accent-2-chroma" | "color-accent-2-hue" | "color-accent-3-bg-luma" | "color-accent-3-fg-luma" | "color-accent-3-chroma" | "color-accent-3-hue" | "shadow-angle" | "shadow-hardness" | "shadow-spread" | "shadow-intensity" | "corner-radius" | "font-family-sans" | "font-family-mono" | "font-family-heading" | "font-family-body" | "font-family-ui" | "font-family-code";
+/**
+ * A pure design token — one CSS custom property, its default, and its display copy. Carries **no**
+ * control metadata; whether it's adjustable is expressed by a separate {@link TokenControl} in
+ * `TOKEN_CONTROLS`. Every token has a `label`/`description` — including the semantic font aliases,
+ * which have no control — so consumers (the token drawer, the reference page) never need a fallback.
+ */
+export interface Token {
+    id: TokenId;
+    /** The `--imf-ui-*` custom property this token writes. Derived from `id` via `toTokenCssVar`. */
+    cssVar: string;
+    default: TokenValue;
+    /** CSS unit appended to numeric values when this token is emitted or applied (for example, `px`). */
+    unit?: string;
+    group: TokenGroup;
+    label: string;
+    description: string;
+}
+/**
+ * A live adjuster bound to a token — the token's own fields plus kind-specific control metadata.
+ * Discriminated on `kind`:
+ * - `slider` — a continuous numeric control (min/max/step); may derive from another token.
+ * - `select` — a discrete choice from an enumerated option list (e.g. font stacks).
+ *
+ * The finer constraint — slider ↔ numeric token, select ↔ string token — is a runtime/test guard, not
+ * encoded here (encoding it would add cryptic type machinery for little gain).
+ */
+export type TokenControl = Token & ({
+    kind: "slider";
+    step: number;
+    min: NumericTokenValue;
+    max: NumericTokenValue;
+    /** When set, the target token inherits this source token's value until explicitly touched. */
+    derivedFrom?: TokenId;
+    /** `single` = one control; `shared` = an envelope control tuning a whole category. */
+    type: "single" | "shared";
+} | {
+    kind: "select";
+    options: readonly {
+        label: string;
+        value: string;
+    }[];
+});
+/** A map of token overrides keyed by full CSS custom property name (e.g. `--imf-ui-color-primary-hue`). */
+export type TokenOverrides = Record<string, number | string>;

package/dist/tokens/use-token-controls.d.ts

@@ -0,0 +1,36 @@
+import { ColorScheme } from '../types/theme';
+import { ResolvedControl } from './apply';
+import { TokenId } from './token-registry';
+import { TokenOverrides } from './types';
+export interface UseTokenControlsResult {
+    /** Every control joined to its token and resolved to the active scheme, carrying its effective value. */
+    controls: readonly ResolvedControl[];
+    setControl: (id: TokenId, value: number | string) => void;
+    setControls: (updates: readonly {
+        id: TokenId;
+        value: number | string;
+    }[]) => void;
+    resetControl: (id: TokenId) => void;
+    reset: () => void;
+}
+/**
+ * The persistence-agnostic token editor. It derives effective values, resolves each control for the
+ * active `scheme`, mirrors the effective map onto `documentElement`, and exposes mutators that
+ * commit through the injected `overrides`/`onChange` pair.
+ *
+ * `useTokenControls` owns *no* persistence — the host decides where `overrides` lives and how writes
+ * are debounced, then passes the current map and a commit callback in on every render.
+ *
+ * **Contract — synchronous read-back:** each mutator builds its next map by spreading the current
+ * `overrides`. If the host debounces persistence, it must still surface each committed map as
+ * `overrides` *synchronously* (e.g. a `useState` working copy) so back-to-back `setControl` calls in
+ * one tick don't clobber each other. A host that only reflects the committed map after an async
+ * round trip will drop rapid successive edits.
+ */
+export declare function useTokenControls({ overrides, onChange, scheme }: {
+    /** Current overrides, keyed by full CSS custom property name. Must update synchronously on commit. */
+    overrides: TokenOverrides;
+    /** Commit the next override map. The host persists it and re-supplies it as `overrides`. */
+    onChange: (next: TokenOverrides) => void;
+    scheme: ColorScheme;
+}): UseTokenControlsResult;

package/dist/types/docgen.d.ts

@@ -0,0 +1,17 @@
+export interface DocgenPropEntry {
+    name: string;
+    required: boolean;
+    type: string;
+    defaultValue: string | null;
+    description: string;
+}
+export interface DocgenComponentEntry {
+    name: string;
+    description: string;
+    props: DocgenPropEntry[];
+}
+export interface DocgenComponentGroup {
+    root: DocgenComponentEntry;
+    subComponents: DocgenComponentEntry[];
+}
+export type DocgenOutput = Record<string, DocgenComponentGroup>;

package/dist/types/meta.d.ts

@@ -0,0 +1,108 @@
+export type ComponentCategoryId = "buttons" | "inputs" | "layout" | "display";
+export type ComponentStatus = "stable" | "experimental" | "deprecated";
+/**
+ * Provenance of a component. `"adapted"` wraps an upstream behavioral package —
+ * Base UI by default, or another best-in-class library (e.g. TanStack Table);
+ * `"native"` is built by us with no upstream runtime dependency, regardless of
+ * whether the design took inspiration from elsewhere. Surfaces as the origin
+ * badge in the docs UI and on consumer-side surfaces that disambiguate the
+ * implementation source.
+ */
+export type ComponentOrigin = "adapted" | "native";
+/**
+ * Upstream a component is adapted from. Required when `origin === "adapted"`,
+ * absent when `origin === "native"`. Carries the human-readable upstream name
+ * (e.g. "Base UI") and the doc URLs the docs UI's link chips point at.
+ */
+export interface ComponentUpstream {
+    /** Display name of the upstream package, e.g. "Base UI". */
+    name: string;
+    /** Upstream brand / project home page — the URL the origin badge links to when clicked. */
+    websiteLink?: string;
+    /** Upstream documentation URL for the human reader. */
+    docLink?: string;
+    /** LLM-friendly documentation URL — typically the `.md` companion of `docLink`. */
+    llmDocLink?: string;
+    /**
+     * Package specifiers a consumer must install to use this primitive, when
+     * adapting from an upstream OTHER than the house dependency (Base UI) — e.g.
+     * `["@tanstack/react-table"]` for Table. Omitted for Base-UI-adapted
+     * primitives, which are already present transitively; an absent field and an
+     * empty array both mean "no extra install". An array (not a single string)
+     * because one adapt may require several independently-installable peers (a
+     * lib plus a required companion package). Docs read this to render an install
+     * hint; `name` remains the human-readable display name.
+     */
+    runtimeDependencies?: string[];
+}
+/**
+ * A taxonomic category as it appears on a component's meta. Carries both the
+ * stable `id` (slug used for grouping/sorting) and a human-readable `label`.
+ * Default labels are English; i18n is out of scope for v0 — a later evolution
+ * can swap `ComponentCategories` for locale-aware sources without changing the
+ * `ComponentCategory` shape consumers read.
+ */
+export interface ComponentCategory {
+    id: ComponentCategoryId;
+    label: string;
+}
+/**
+ * Canonical category objects. Every `*.meta.ts` should reference one of these
+ * (e.g. `category: ComponentCategories.inputs`) rather than inlining a literal
+ * — a literal allows ID/label drift and duplicates the label string per meta.
+ */
+export declare const ComponentCategories: {
+    readonly buttons: {
+        readonly id: "buttons";
+        readonly label: "Buttons";
+    };
+    readonly inputs: {
+        readonly id: "inputs";
+        readonly label: "Inputs";
+    };
+    readonly layout: {
+        readonly id: "layout";
+        readonly label: "Layout";
+    };
+    readonly display: {
+        readonly id: "display";
+        readonly label: "Display";
+    };
+};
+/**
+ * Self-descriptive metadata for an exported component. Describes *what the
+ * component is* — name, taxonomy, lifecycle, a one-sentence identity line, and
+ * provenance (adapted from an upstream vs. native). NOT documentation prose,
+ * usage examples, props, or part enumerations. Props are derived from the
+ * component's TypeScript Props interface at build time; longer-form
+ * documentation lives in MDX; named sub-exports are the source of truth for
+ * compound-component parts.
+ */
+export interface ComponentMeta {
+    /** PascalCase component name as exported from `@imfusion/web-ui`. Matches the `data-imf-ui-component` attribute. */
+    name: string;
+    /** Taxonomic category. Use a `ComponentCategories.*` constant. */
+    category: ComponentCategory;
+    /** Lifecycle marker. Required and explicit on every meta. */
+    status: ComponentStatus;
+    /**
+     * Set to `true` for pure-namespace components (e.g. Typo) that intentionally
+     * have no `Root` export — every export is a named sub-component. Suppresses
+     * the docgen "no root component found" warning for this folder.
+     */
+    namespace?: true;
+    /** One-sentence identity line. Rendered in the docs UI page header and reusable on consumer-side surfaces (nav tooltips, search). Not a paragraph; not example prose. */
+    description: string;
+    /** Provenance — `"adapted"` wraps an upstream package, `"native"` is built by us. */
+    origin: ComponentOrigin;
+    /** Upstream descriptor — required when `origin === "adapted"`, absent when `origin === "native"`. */
+    upstream?: ComponentUpstream;
+    /**
+     * PascalCase names of other `@imfusion/web-ui` components this component
+     * composes internally (e.g. CopyButton renders through Button).
+     * The in-library counterpart to `upstream.runtimeDependencies`: no install
+     * implication — purely discovery/documentation, surfaced by doc tooling
+     * (DocHeader "Uses" row). Omit when the component composes nothing.
+     */
+    internalDependencies?: string[];
+}

package/dist/types/theme.d.ts

@@ -0,0 +1,3 @@
+import { config } from '../config';
+export type ColorScheme = "light" | "dark";
+export type ColorSchemePreference = (typeof config.colorScheme.options)[number];

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "@imfusion/web-ui",
+  "version": "0.5.0",
+  "description": "The official Web UI component library for ImFusion web apps",
+  "author": "ImFusion GmbH",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "restricted"
+  },
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "web-ui-install-skills": "./bin/install-skill.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./integrations/*": {
+      "types": "./dist/integrations/*/index.d.ts",
+      "import": "./dist/integrations/*.js"
+    },
+    "./styles.css": "./dist/style.css",
+    "./docgen.json": "./src/docgen/doc.gen.json",
+    "./llms.txt": "./src/llms/llms.gen.txt",
+    "./*": null
+  },
+  "files": [
+    "dist",
+    "src/docgen/doc.gen.json",
+    "src/llms/llms.gen.txt",
+    "src/llms/skills",
+    "bin"
+  ],
+  "scripts": {
+    "codegen:docgen": "tsx src/docgen/gen-docgen.ts",
+    "codegen:llms": "tsx src/llms/gen-llms.ts",
+    "codegen:watch": "tsx watch src/codegen/run.ts",
+    "codegen:storybook": "tsx src/codegen/run.ts --storybook",
+    "codegen": "tsx src/codegen/run.ts",
+    "build": "npm run codegen && rm -rf dist && vite build && npm run codegen:docgen && npm run codegen:llms",
+    "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\"",
+    "typecheck": "npm run codegen && tsc -p tsconfig.lib.json --noEmit && tsc -p .storybook/tsconfig.json --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint . --cache --max-warnings=0",
+    "lint:fix": "eslint . --cache --fix",
+    "lint:inspect": "npx @eslint/config-inspector@latest",
+    "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",
+    "storybook": "npm run codegen:storybook && storybook dev -p 6006 --no-open",
+    "storybook:free-ports": "tsx scripts/free-storybook-ports.ts",
+    "build:storybook": "npm run codegen:storybook && storybook build",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:stories": "vitest run --project storybook",
+    "test:watch": "vitest",
+    "verify:preflight": "tsx scripts/verify/full.ts",
+    "verify:full": "npm run verify:preflight && npm run test",
+    "worktree:create": "tsx scripts/worktrees.ts create",
+    "worktree:close": "tsx scripts/worktrees.ts close",
+    "worktree:discard": "tsx scripts/worktrees.ts discard",
+    "knip": "knip",
+    "prepare": "git config core.hooksPath .githooks && git config pull.rebase true && git config merge.ff only"
+  },
+  "peerDependencies": {
+    "@imfusion/sdk": "^1.0.0",
+    "@imfusion/sdk-react": "^1.0.0",
+    "@tanstack/highlight": "^0.0.9",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@imfusion/sdk": {
+      "optional": true
+    },
+    "@imfusion/sdk-react": {
+      "optional": true
+    },
+    "@tanstack/highlight": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@base-ui/react": "1.6.0",
+    "@clack/prompts": "1.7.0",
+    "class-variance-authority": "0.7.1",
+    "lucide-react": "1.16.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "1.4.1",
+    "@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",
+    "@tanstack/react-pacer": "0.22.1",
+    "@types/culori": "4.0.1",
+    "@types/mdx": "2.0.13",
+    "@types/node": "25.6.0",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "6.0.1",
+    "@vitest/browser-playwright": "4.1.6",
+    "concurrently": "9.2.1",
+    "culori": "4.0.2",
+    "eslint": "9.39.4",
+    "eslint-plugin-jsx-a11y": "6.10.2",
+    "eslint-plugin-mdx": "3.7.0",
+    "eslint-plugin-react": "7.37.5",
+    "eslint-plugin-react-hooks": "5.2.0",
+    "eslint-plugin-react-refresh": "0.4.26",
+    "globals": "15.15.0",
+    "jiti": "2.7.0",
+    "knip": "6.14.2",
+    "nano-staged": "1.0.2",
+    "playwright": "1.60.0",
+    "prettier": "3.8.3",
+    "react-docgen-typescript": "2.4.0",
+    "storybook": "10.4.3",
+    "tsx": "4.21.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.59.3",
+    "vite": "8.0.10",
+    "vite-plugin-dts": "5.0.0",
+    "vitest": "4.1.6"
+  }
+}