@vertesia/ui 1.5.0 → 1.6.0-dev.20260918.061604Z

package/lib/widgets/xml-viewer/hooks/useCollapsible.d.ts

@@ -1,8 +1,8 @@
 export declare function useCollapsible(level: number): {
     collapsed: boolean;
     buttonProps: {
-        role?: undefined;
         onClick?: undefined;
+        role?: undefined;
         style?: undefined;
     } | {
         onClick: () => void;

package/llms.txt

@@ -505,8 +505,12 @@ Semantic Tailwind classes and approved lucide-react icon guidance for Vertesia a
 
 ### Notes
 
-- Examples: `text-success`, `bg-attention`, `border-destructive`, `bg-mixer-muted/30`.
-- Avoid hardcoded color values in application UI.
+- Examples: `text-success-foreground`, `bg-attention`, `border-destructive-foreground`, `bg-mixer-muted/30`.
+- Pages: `bg-background text-foreground`; cards: `bg-card text-card-foreground` (white in light mode).
+- Reserve `bg-muted` for subdued sections; muted text uses `text-muted-foreground`.
+- Primary buttons pair `bg-primary text-primary-foreground`; prefer `<Button>` without color overrides.
+- Base names are surfaces; `-foreground` names are text/icons. `/50` changes opacity of the named token.
+- Avoid hardcoded gray/black/white app surfaces and manual dark-mode surface overrides.
 
 # Key Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/ui",
-  "version": "1.5.0",
+  "version": "1.6.0-dev.20260918.061604Z",
   "description": "Vertesia UI components and and hooks",
   "type": "module",
   "main": "./lib/index.js",
@@ -45,38 +45,43 @@
     "@radix-ui/react-switch": "^1.3.7",
     "@radix-ui/react-tabs": "^1.1.21",
     "@radix-ui/react-tooltip": "^1.2.16",
+    "@vertesia/client": "1.6.0-dev.20260918.061604Z",
+    "@vertesia/common": "1.6.0-dev.20260918.061604Z",
+    "@vertesia/fusion-ux": "1.6.0-dev.20260918.061604Z",
+    "@vertesia/json": "1.6.0-dev.20260918.061604Z",
+    "@vertesia/rich-text": "1.6.0-dev.20260918.061604Z",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "aria-hidden": "^1.2.6",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
-    "dayjs": "^1.11.21",
+    "dayjs": "^1.11.23",
     "debounce": "^3.0.0",
-    "dompurify": "^3.4.13",
-    "fast-xml-parser": "^5.10.1",
-    "firebase": "^12.17.1",
-    "framer-motion": "^12.43.0",
-    "i18next": "^26.3.6",
+    "dompurify": "^3.4.15",
+    "fast-xml-parser": "^5.11.1",
+    "firebase": "^12.18.0",
+    "framer-motion": "^13.2.0",
+    "i18next": "^26.4.2",
     "jwt-decode": "^4.0.0",
-    "katex": "^0.18.4",
+    "katex": "^0.18.7",
     "lodash-es": "^4.18.1",
-    "lucide-react": "^1.31.0",
-    "mermaid": "^11.16.1",
+    "lucide-react": "^1.42.0",
+    "mermaid": "^11.17.2",
     "monaco-editor": "^0.56.0",
-    "motion": "^12.43.0",
-    "papaparse": "^5.5.4",
-    "react": "19.2.7",
+    "motion": "^13.2.0",
+    "papaparse": "^5.7.0",
+    "react": "19.2.8",
     "react-calendar": "^6.0.1",
     "react-date-picker": "^12.1.0",
-    "react-dom": "19.2.7",
-    "react-error-boundary": "^6.1.3",
-    "react-i18next": "^17.0.11",
+    "react-dom": "19.2.8",
+    "react-error-boundary": "^6.1.5",
+    "react-i18next": "^17.0.13",
     "react-markdown": "^10.1.0",
-    "react-pdf": "^10.4.1",
+    "react-pdf": "^10.5.0",
     "react-remove-scroll": "^2.7.2",
     "react-remove-scroll-bar": "^2.3.8",
-    "react-resizable-panels": "^4.12.3",
+    "react-resizable-panels": "^4.12.4",
     "react-style-singleton": "^2.2.3",
     "react-vega": "^8.0.0",
     "rehype-katex": "^7.0.1",
@@ -89,34 +94,30 @@
     "tailwind-merge": "^3.6.0",
     "ts-md5": "^2.0.1",
     "unist-util-visit": "^5.1.0",
-    "vega": "^6.3.1",
-    "vega-embed": "^7.1.0",
-    "vega-lite": "^6.4.3",
-    "@vertesia/fusion-ux": "1.5.0",
-    "@vertesia/common": "1.5.0",
-    "@vertesia/json": "1.5.0",
-    "@vertesia/rich-text": "1.5.0",
-    "@vertesia/client": "1.5.0"
+    "vega": "^6.4.0",
+    "vega-embed": "^7.2.0",
+    "vega-lite": "^6.4.3"
   },
   "devDependencies": {
-    "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.4",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.7",
     "@types/hast": "^3.0.5",
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^24.13.3",
     "@types/papaparse": "^5.5.2",
-    "@types/react": "19.2.17",
-    "@types/react-dom": "19.2.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "@vertesia/tsconfig": "0.1.0",
     "axe-core": "^4.13.0",
     "culori": "^4.0.2",
-    "i18next-cli": "^1.69.0",
+    "i18next-cli": "^1.73.1",
     "jsdom": "^30.0.1",
-    "rolldown": "1.2.4",
+    "rolldown": "1.2.8",
+    "tailwindcss": "^4.3.3",
     "typescript": "7.0.2",
-    "vitest": "^4.1.10",
+    "vitest": "5.0.0",
     "vitest-axe": "^0.1.0",
-    "wcag-contrast": "^3.0.0",
-    "@vertesia/tsconfig": "0.1.0"
+    "wcag-contrast": "^3.0.0"
   },
   "exports": {
     "./styles.css": "./src/css/index.css",
@@ -133,6 +134,10 @@
     "./css/typography.css": "./src/css/typography.css",
     "./css/custom-tooltips.css": "./src/css/custom-tooltips.css",
     "./css/base.css": "./src/css/base.css",
+    "./boot": {
+      "types": "./lib/boot/index.d.ts",
+      "default": "./lib/boot/index.js"
+    },
     "./router": {
       "types": "./lib/router/index.d.ts",
       "default": "./lib/router/index.js"
@@ -172,6 +177,10 @@
     "./i18n": {
       "types": "./lib/i18n/index.d.ts",
       "default": "./lib/i18n/index.js"
+    },
+    "./boot/vite": {
+      "types": "./lib/boot/vite.d.ts",
+      "default": "./lib/boot/vite.js"
     }
   },
   "repository": {
@@ -179,7 +188,7 @@
     "url": "https://github.com/vertesia/composableai.git",
     "directory": "packages/ui"
   },
-  "gitHead": "3485742020066ab1fd3292487cf3a9577b5e4d91",
+  "gitHead": "ea552337206e77c256478b76e19b4235e70bf769",
   "scripts": {
     "clean:lib": "rimraf ./lib ./tsconfig.tsbuildinfo",
     "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo",

package/src/__tests__/a11y.test.tsx

@@ -26,6 +26,31 @@ describe('@vertesia/ui accessibility (axe)', () => {
         expect(await axe(container)).toHaveNoViolations();
     });
 
+    it('Button resolves custom color overrides without conflicting variant colors', () => {
+        const { container } = renderWithProviders(
+            <div>
+                <Button>Save</Button>
+                <Button className="bg-info text-info">Custom action</Button>
+                <Button variant="outline">Cancel</Button>
+            </div>,
+        );
+        const [primary, custom, outline] = container.querySelectorAll('button');
+        // The primary variant is the solid brand pair: `bg-primary` is the dark blue surface and
+        // `text-primary` resolves `--primary-foreground` (white) on top of it. Both halves use the
+        // bare token name -- `text-primary-foreground` is the pre-rename spelling and must not return.
+        expect(primary.classList.contains('bg-primary')).toBe(true);
+        expect(primary.classList.contains('text-primary')).toBe(true);
+        expect(primary.classList.contains('text-primary-foreground')).toBe(false);
+        // A className color override replaces the variant's pair outright, leaving no primary remnant.
+        expect(custom.classList.contains('bg-info')).toBe(true);
+        expect(custom.classList.contains('text-info')).toBe(true);
+        expect(custom.classList.contains('bg-primary')).toBe(false);
+        expect(custom.classList.contains('text-primary')).toBe(false);
+        // The outline variant sets a surface but no semantic ink, so it inherits the page foreground.
+        expect(outline.classList.contains('bg-background')).toBe(true);
+        expect(outline.classList.contains('text-primary')).toBe(false);
+    });
+
     it('Button defaults to type="button" but does not inject type when asChild', async () => {
         const { container } = renderWithProviders(
             <div>

package/src/__tests__/theme.test.ts

@@ -0,0 +1,91 @@
+// @vitest-environment node
+/**
+ * Token contract gate. The three assertions here are convention-agnostic:
+ * every exposed --color-* resolves, every binding is emitted, and utilities stay
+ * bound to the alias so scoped overrides work.
+ *
+ * The surface/foreground pairing assertions that shipped with the -foreground
+ * convention were removed with it; re-add equivalents for `bg-X` -> --color-X-background.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { compile } from 'tailwindcss';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+const readCss = (name: string) => readFileSync(new URL(`../css/${name}.css`, import.meta.url), 'utf8');
+const colorCss = readCss('color');
+const themeCss = readCss('theme');
+let build: (classes: string[]) => string;
+let source: string;
+
+beforeAll(async () => {
+    const tailwindTheme = readFileSync(fileURLToPath(import.meta.resolve('tailwindcss/theme.css')), 'utf8');
+    source = `${tailwindTheme}\n${colorCss}\n${themeCss}\n${readCss('utilities')}\n@tailwind utilities;`;
+    ({ build } = await compile(source));
+});
+
+function declarations(block: string): Map<string, string> {
+    return new Map([...block.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)].map((m) => [m[1], m[2].trim()]));
+}
+
+function resolve(name: string, tokens: Map<string, string>, seen = new Set<string>()): string {
+    if (seen.has(name)) throw new Error(`Cyclic theme token: ${name}`);
+    const value = tokens.get(name);
+    if (!value) throw new Error(`Undefined theme token: ${name}`);
+    const next = new Set(seen).add(name);
+    return value.replace(/var\((--[\w-]+)\)/g, (_, ref: string) => resolve(ref, tokens, next));
+}
+
+function rule(css: string, className: string): string {
+    const selector = `.${className.replaceAll('/', '\\/')} {`;
+    const start = css.indexOf(selector);
+    expect(start, `Missing utility ${className}`).toBeGreaterThanOrEqual(0);
+    let depth = 1;
+    let end = start + selector.length;
+    while (depth && end < css.length) {
+        if (css[end] === '{') depth++;
+        if (css[end] === '}') depth--;
+        end++;
+    }
+    return css.slice(start + selector.length, end - 1);
+}
+
+describe('theme utility contract', () => {
+    for (const mode of [':root', '.dark']) {
+        it(`resolves every exposed color in ${mode}`, () => {
+            const root = colorCss.match(/:root\s*\{([^}]+)\}/)?.[1] ?? '';
+            const dark = colorCss.match(/\.dark\s*\{([^}]+)\}/)?.[1] ?? '';
+            const tokens = declarations(`${root}\n${mode === '.dark' ? dark : ''}\n${themeCss}`);
+            for (const name of tokens.keys()) {
+                if (name.startsWith('--color-')) {
+                    expect(resolve(name, tokens), name).not.toContain('var(');
+                }
+            }
+        });
+    }
+
+    it('emits every color binding even without utility or stylesheet consumers', async () => {
+        const fresh = await compile(source);
+        const emitted = declarations(fresh.build([]));
+        for (const [name, value] of declarations(themeCss)) {
+            if (name.startsWith('--color-')) {
+                expect(emitted.get(name), name).toBe(value);
+            }
+        }
+    });
+
+    it('keeps utilities bound to color aliases so scoped overrides take effect', () => {
+        const classes = [
+            'bg-sidebar',
+            'text-sidebar-foreground',
+            'bg-sidebar-accent',
+            'text-sidebar-accent-foreground',
+            'border-sidebar-border',
+        ];
+        const css = build(classes);
+        for (const className of classes) {
+            const token = className.replace(/^(bg|text|border)-/, '--color-');
+            expect(rule(css, className)).toContain(`var(${token})`);
+        }
+    });
+});

package/src/boot/branding.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+import { brandedBootOptions, renderBrandStyles } from './branding.js';
+import { injectBootScreenHtml, renderDefaultBootContent } from './index.js';
+
+describe('shared app branding', () => {
+    it('escapes brand copy and logos in first paint and keeps recovery controls', () => {
+        const options = brandedBootOptions({
+            name: '<script>alert(1)</script>',
+            loadingIcon: { light: 'logo.svg" onerror="bad' },
+            copy: { loading: 'A & B' },
+        });
+        const root = document.createElement('div');
+        root.innerHTML = renderDefaultBootContent(options);
+        expect(root.querySelector('script')).toBeNull();
+        expect(root.querySelector('img')?.getAttribute('onerror')).toBeNull();
+        expect(root.querySelector('h1')).toBeNull();
+        expect(root.querySelector('[data-boot-reload]')?.className).toBe('vboot-btn');
+        expect(root.querySelector('#loading-slow-notice')?.className).toBe('vboot-slow');
+        expect(root.querySelector('#loading-slow-notice p')).toBeTruthy();
+        expect(root.querySelector<HTMLElement>('#loading-slow-reload')?.style.display).toBe('none');
+        const html = injectBootScreenHtml('<html><head></head><body><div id="root"></div></body></html>', options);
+        expect(html).not.toContain('<script>alert(1)</script>');
+    });
+
+    it('scopes React colors and keeps decorative accents separate from button text', () => {
+        const css = renderBrandStyles(
+            { name: 'Test', colors: { light: { accent: '#ff6200' }, dark: { background: '#161d26' } } },
+            '[data-vbrand="one"]',
+        );
+        expect(css).toContain('[data-vbrand="one"] {');
+        expect(css).not.toContain('display:');
+        expect(css).not.toContain('padding:');
+        expect(css).toContain('--info:#ff6200');
+        expect(css).toContain('--color-background:#161d26');
+        expect(renderDefaultBootContent(brandedBootOptions({ name: 'Test' }))).toBe(renderDefaultBootContent());
+        expect(css).not.toContain('.vbrand {');
+    });
+
+    it('shares custom animation and keyframes between React and boot, and supports static logos', () => {
+        const brand = {
+            name: 'Test',
+            loadingIcon: {
+                light: 'icon.svg',
+                animation: 'example-dim 2s ease-in-out infinite',
+                keyframes: '@keyframes example-dim { 50% { opacity: 0.35; } }',
+            },
+        };
+        for (const css of [renderBrandStyles(brand), brandedBootOptions(brand).styles]) {
+            expect(css).toContain('--vertesia-loading-animation:example-dim 2s ease-in-out infinite;');
+            expect(css).toContain('--vertesia-loading-pulse-animation:none;');
+            expect(css).toContain(brand.loadingIcon.keyframes);
+        }
+        expect(renderBrandStyles({ name: 'Default' })).not.toContain('--vertesia-loading-animation:');
+        expect(renderBrandStyles({ ...brand, loadingIcon: { light: 'icon.svg', animation: 'none' } })).toContain(
+            '--vertesia-loading-animation:none;',
+        );
+        expect(() =>
+            renderBrandStyles({ ...brand, loadingIcon: { light: 'icon.svg', animation: 'none;}body{}' } }),
+        ).toThrow('Invalid loading icon animation');
+        expect(() =>
+            renderBrandStyles({ ...brand, loadingIcon: { light: 'icon.svg', keyframes: '</style>' } }),
+        ).toThrow('Invalid loading icon keyframes');
+    });
+
+    it('rejects CSS declaration injection and escapes font names', () => {
+        expect(() =>
+            renderBrandStyles({ name: 'Test', colors: { light: { background: 'red;}body{display:none' } } }),
+        ).toThrow('Invalid branding color');
+        const css = renderBrandStyles({ name: 'Test', font: { family: '</style>', regular: 'font.woff2' } });
+        expect(css).not.toContain('</style>');
+    });
+});

package/src/boot/branding.ts

@@ -0,0 +1,108 @@
+/** Data-only branding shared by the build-time boot screen and the React shell. */
+export interface AppBranding {
+    name: string;
+    title?: string;
+    logo?: { light: string; dark?: string; alt?: string };
+    favicon?: string;
+    /** Small icon used by the existing loading layouts. */
+    loadingIcon?: {
+        light: string;
+        dark?: string;
+        /** CSS animation shorthand for boot and auth loading. Use 'none' for a static logo. */
+        animation?: string;
+        /** Trusted app-authored @keyframes CSS, shared by boot and React. Use app-specific names. */
+        keyframes?: string;
+    };
+    font?: { family: string; regular: string; bold?: string };
+    colors?: { light?: BrandColors; dark?: BrandColors };
+    copy?: {
+        welcome?: string;
+        emailPlaceholder?: string;
+        loading?: string;
+        slowLoading?: string;
+        reload?: string;
+        footer?: string;
+        /** Optional auth./signup. translation overrides, local to this shell. */
+        translations?: Record<string, string>;
+    };
+    /** File paths in source configuration; trusted HTML/CSS content after build-time resolution. */
+    boot?: { html?: string; styles?: string };
+}
+
+export interface BrandColors {
+    background?: string;
+    foreground?: string;
+    /** Decorative accents, focus indicators, and spinners; never used as body text. */
+    accent?: string;
+    button?: string;
+    buttonText?: string;
+}
+
+export function defineAppBranding(branding: AppBranding): AppBranding {
+    return branding;
+}
+
+export function escapeBrandHtml(value: string): string {
+    return value.replace(
+        /[&<>"']/g,
+        (char) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char] ?? char,
+    );
+}
+
+function cssString(value: string): string {
+    return JSON.stringify(value).replace(/</g, '\\3c ');
+}
+
+function colorDeclarations(colors?: BrandColors): string {
+    const variables: Record<keyof BrandColors, string[]> = {
+        background: ['--background', '--color-background', '--vb-bg'],
+        foreground: ['--foreground', '--color-foreground', '--vb-fg'],
+        accent: ['--info', '--info-foreground', '--color-info', '--color-info-foreground'],
+        button: ['--primary', '--color-primary', '--vb-primary', '--auth-button'],
+        buttonText: ['--primary-foreground', '--color-primary-foreground', '--vb-primary-fg', '--auth-button-text'],
+    };
+    return Object.entries(colors ?? {})
+        .map(([key, value]) => {
+            if (!Object.hasOwn(variables, key) || /[;{}<>]/.test(value))
+                throw new Error(`Invalid branding color: ${key}`);
+            return variables[key as keyof BrandColors].map((name) => `${name}:${value};`).join('');
+        })
+        .join('');
+}
+
+/** Theme tokens only: branding must never replace the shared page layout. */
+export function renderBrandStyles(brand: AppBranding, selector = '.vbrand'): string {
+    const animation = brand.loadingIcon?.animation;
+    const keyframes = brand.loadingIcon?.keyframes ?? '';
+    if (animation !== undefined && /[;{}<>]/.test(animation)) throw new Error('Invalid loading icon animation');
+    if (/[<>]/.test(keyframes)) throw new Error('Invalid loading icon keyframes');
+    const motion =
+        animation === undefined
+            ? ''
+            : `--vertesia-loading-animation:${animation};--vertesia-loading-pulse-animation:none;`;
+    const font = brand.font;
+    const faces = font
+        ? `@font-face { font-family:${cssString(font.family)};src:url(${cssString(font.regular)});font-weight:400;font-display:swap; }
+${font.bold ? `@font-face { font-family:${cssString(font.family)};src:url(${cssString(font.bold)});font-weight:700;font-display:swap; }` : ''}`
+        : '';
+    return `${faces}
+${keyframes}
+${selector} { ${motion}${colorDeclarations(brand.colors?.light)}${font ? `font-family:${cssString(font.family)};` : ''} }
+.dark ${selector},${selector}.vboot-dark { ${colorDeclarations(brand.colors?.dark)} }
+`;
+}
+
+export function brandedBootOptions(brand: AppBranding): import('./index.js').BootScreenOptions {
+    return {
+        iconSrc: brand.loadingIcon?.light,
+        darkIconSrc: brand.loadingIcon?.dark,
+        loadingLabel: brand.copy?.loading,
+        slowLoadingLabel: brand.copy?.slowLoading,
+        reloadLabel: brand.copy?.reload,
+        html: brand.boot?.html,
+        styles: `${renderBrandStyles(brand, '#loading-indicator')}
+${brand.colors?.light?.background ? `:root{--vertesia-boot-background:${brand.colors.light.background}}` : ''}
+${brand.colors?.dark?.background ? `:root.dark{--vertesia-boot-background:${brand.colors.dark.background}}` : ''}
+${brand.boot?.styles ?? ''}`,
+    };
+}